portacode 1.4.15.dev0__tar.gz → 1.4.15.dev2__tar.gz

{portacode-1.4.15.dev0 → portacode-1.4.15.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: portacode
-Version: 1.4.15.dev0
+Version: 1.4.15.dev2
 Summary: Portacode CLI client and SDK
 Home-page: https://github.com/portacode/portacode
 Author: Meena Erian

{portacode-1.4.15.dev0 → portacode-1.4.15.dev2}/portacode/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '1.4.15.dev0'
-__version_tuple__ = version_tuple = (1, 4, 15, 'dev0')
+__version__ = version = '1.4.15.dev2'
+__version_tuple__ = version_tuple = (1, 4, 15, 'dev2')
 
 __commit_id__ = commit_id = None

{portacode-1.4.15.dev0 → portacode-1.4.15.dev2}/portacode/connection/handlers/WEBSOCKET_PROTOCOL.md

@@ -331,6 +331,8 @@ Configures a Proxmox node for Portacode infrastructure usage (API token validati
 *   `verify_ssl` (boolean, optional): When true, the handler verifies SSL certificates; defaults to `false`. When omitted, the last configured value is preserved.
 *   `cloudflare_api_token` (string, optional): Cloudflare API token the host can reuse later to provision tunnels.
 
+The setup command also installs `cloudflared` on the node so Cloudflare tunnels can be created afterward.
+
 **Responses:**
 
 *   On success, the device will emit a [`proxmox_infra_configured`](#proxmox_infra_configured-event) event with the persisted infra snapshot.
@@ -410,6 +412,51 @@ Deletes a managed container from Proxmox (stopping it first if necessary) and re
 *   Emits a [`proxmox_container_action`](#proxmox_container_action-event) event with `action="remove"` and the refreshed infra snapshot after deletion.
 *   Emits an [`error`](#error) event on failure.
 
+### `create_cloudflare_tunnel`
+
+Creates or updates a Cloudflare tunnel in front of a managed container. The container must be running and a Cloudflare API token must already be configured via `setup_proxmox_infra`.
+
+**Payload Fields:**
+
+*   `ctid` (string, required): Identifier of the container.
+*   `container_port` (integer, required): Port inside the container to expose through Cloudflare.
+*   `cloudflare_url` (string, optional): Hostname (e.g., `app.example.com`) that the tunnel should serve. Leave blank to let Cloudflare create a quick tunnel (`*.cfargotunnel.com`) automatically.
+*   `protocol` (string, optional): One of `http`, `https`, or `tcp` (defaults to `http`).
+
+**Responses:**
+
+*   Emits a [`cloudflare_tunnel_created`](#cloudflare_tunnel_created-event) event with the tunnel metadata.
+*   Emits an [`error`](#error) event on failure.
+
+### `update_cloudflare_tunnel`
+
+Refreshes the tunnel configuration for an existing tunnel (different port, URL, or protocol).
+
+**Payload Fields:**
+
+*   `ctid` (string, required): Identifier of the container.
+*   `container_port` (integer, optional): New container port.
+*   `cloudflare_url` (string, optional): New hostname (leave blank to keep the current hostname or let Cloudflare assign a quick tunnel).
+*   `protocol` (string, optional): New protocol (`http`, `https`, or `tcp`).
+
+**Responses:**
+
+*   Emits a [`cloudflare_tunnel_updated`](#cloudflare_tunnel_updated-event) event with the refreshed tunnel metadata.
+*   Emits an [`error`](#error) event on failure.
+
+### `remove_cloudflare_tunnel`
+
+Stops and removes any tunnel metadata associated with a container.
+
+**Payload Fields:**
+
+*   `ctid` (string, required): Identifier of the container.
+
+**Responses:**
+
+*   Emits a [`cloudflare_tunnel_removed`](#cloudflare_tunnel_removed-event) event.
+*   Emits an [`error`](#error) event on failure.
+
 ### `proxmox_container_created`
 
 Emitted after a successful `create_proxmox_container` action. Contains the new container ID, the Portacode public key produced inside the container, and the bootstrap logs.
@@ -1146,6 +1193,11 @@ Provides system information in response to a `system_info` action. Handled by [`
                         *   `cpu_share` (number): vCPU-equivalent share requested at creation.
                         *   `status` (string): Lowercase lifecycle status (e.g., `running`, `stopped`, `deleted`).
                         *   `created_at` (string|null): ISO timestamp recorded when the CT was provisioned.
+                        *   `tunnel` (object|null): Tunnel metadata that includes:
+                            *   `url` (string): Public hostname assigned for this tunnel.
+                            *   `container_port` (integer): Container port exposed via the tunnel.
+                            *   `protocol` (string): Protocol advertised when the tunnel was configured.
+                            *   `status` (string): `running`, `stopped`, or `unknown`.
     *   `portacode_version` (string): Installed CLI version returned by `portacode.__version__`.
 
 ### `proxmox_infra_configured`
@@ -1211,6 +1263,41 @@ Emitted after `start_proxmox_container`, `stop_proxmox_container`, or `remove_pr
 *   `details` (object, optional): Exit status information (e.g., `exitstatus`, `stop_exitstatus`, `delete_exitstatus`).
 *   `infra` (object): Same snapshot described under [`system_info`](#system_info-event) `proxmox.infra`, including the updated `managed_containers` summary.
 
+### `cloudflare_tunnel_created`
+
+Submitted after a successful `create_cloudflare_tunnel` action.
+
+**Event Fields:**
+
+*   `event` (string): `cloudflare_tunnel_created`.
+*   `ctid` (string): Container ID associated with the tunnel.
+*   `success` (boolean): True when the tunnel is running.
+*   `message` (string): Summary text.
+*   `tunnel` (object): Tunnel metadata matching the manager view. When using Cloudflare Quick Tunnel (no hostname supplied), `tunnel.url` holds the autogenerated `*.cfargotunnel.com` hostname.
+
+### `cloudflare_tunnel_updated`
+
+Sent when `update_cloudflare_tunnel` completes.
+
+**Event Fields:**
+
+*   `event` (string): `cloudflare_tunnel_updated`.
+*   `ctid` (string): Container ID associated with the tunnel.
+*   `success` (boolean): True on success.
+*   `message` (string): Summary text.
+*   `tunnel` (object): Updated tunnel metadata.
+
+### `cloudflare_tunnel_removed`
+
+Sent after a tunnel has been removed from a container record.
+
+**Event Fields:**
+
+*   `event` (string): `cloudflare_tunnel_removed`.
+*   `ctid` (string): Container ID that no longer has a tunnel.
+*   `success` (boolean): True on success.
+*   `message` (string): Summary text.
+
 ### <a name="clock_sync_response"></a>`clock_sync_response`
 
 Reply sent by the gateway immediately after receiving a `clock_sync_request`. Devices use this event plus the measured round-trip time to keep their local `ntp_clock` offset accurate.

{portacode-1.4.15.dev0 → portacode-1.4.15.dev2}/portacode/connection/handlers/proxmox_infra.py

@@ -8,6 +8,8 @@ import logging
 import os
 import secrets
 import shlex
+import re
+import select
 import shutil
 import stat
 import subprocess
@@ -15,6 +17,7 @@ import sys
 import tempfile
 import time
 import threading
+import urllib.request
 from datetime import datetime
 from pathlib import Path
 from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence, Tuple
@@ -40,12 +43,15 @@ BRIDGE_IP = SUBNET_CIDR.split("/", 1)[0]
 DHCP_START = "10.10.0.100"
 DHCP_END = "10.10.0.200"
 DNS_SERVER = "1.1.1.1"
+CLOUDFLARE_DEB_URL = "https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb"
 IFACES_PATH = Path("/etc/network/interfaces")
 SYSCTL_PATH = Path("/etc/sysctl.d/99-portacode-forward.conf")
 UNIT_DIR = Path("/etc/systemd/system")
 _MANAGED_CONTAINERS_CACHE_TTL_S = 30.0
 _MANAGED_CONTAINERS_CACHE: Dict[str, Any] = {"timestamp": 0.0, "summary": None}
 _MANAGED_CONTAINERS_CACHE_LOCK = threading.Lock()
+_CLOUDFLARE_TUNNEL_PROCESSES: Dict[str, subprocess.Popen] = {}
+_CLOUDFLARE_TUNNELS_LOCK = threading.Lock()
 
 ProgressCallback = Callable[[int, int, Dict[str, Any], str, Optional[Dict[str, Any]]], None]
 
@@ -279,6 +285,25 @@ def _ensure_bridge(bridge: str = DEFAULT_BRIDGE) -> Dict[str, Any]:
     return {"applied": True, "bridge": bridge, "message": f"Bridge {bridge} configured"}
 
 
+def _ensure_cloudflared_installed() -> None:
+    if shutil.which("cloudflared"):
+        return
+    apt = shutil.which("apt-get")
+    if not apt:
+        raise RuntimeError("cloudflared is missing and apt-get is unavailable to install it")
+    download_dir = Path(tempfile.mkdtemp())
+    deb_path = download_dir / "cloudflared.deb"
+    try:
+        urllib.request.urlretrieve(CLOUDFLARE_DEB_URL, deb_path)
+        try:
+            _call_subprocess(["dpkg", "-i", str(deb_path)], check=True)
+        except subprocess.CalledProcessError:
+            _call_subprocess([apt, "install", "-f", "-y"], check=True)
+            _call_subprocess(["dpkg", "-i", str(deb_path)], check=True)
+    finally:
+        shutil.rmtree(download_dir, ignore_errors=True)
+
+
 def _verify_connectivity(timeout: float = 5.0) -> bool:
     try:
         _call_subprocess(["/bin/ping", "-c", "2", "1.1.1.1"], check=True, timeout=timeout)
@@ -355,6 +380,7 @@ def _build_managed_containers_summary(records: List[Dict[str, Any]]) -> Dict[str
                 "cpu_share": cpu_share,
                 "created_at": record.get("created_at"),
                 "status": status,
+                "tunnel": record.get("tunnel"),
             }
         )
 
@@ -592,6 +618,89 @@ def _remove_container_record(vmid: int) -> None:
         _invalidate_managed_containers_cache()
 
 
+def _update_container_tunnel(vmid: int, tunnel: Optional[Dict[str, Any]]) -> None:
+    record = _read_container_record(vmid)
+    if tunnel:
+        record["tunnel"] = tunnel
+    else:
+        record.pop("tunnel", None)
+    _write_container_record(vmid, record)
+
+
+def _ensure_cloudflare_token(config: Dict[str, Any]) -> str:
+    cloudflare = config.get("cloudflare") or {}
+    token = cloudflare.get("api_token")
+    if not token:
+        raise RuntimeError("Cloudflare API token is not configured.")
+    return token
+
+
+def _launch_container_tunnel(proxmox: Any, node: str, vmid: int, tunnel: Dict[str, Any]) -> Dict[str, Any]:
+    port = int(tunnel.get("container_port") or 0)
+    if not port:
+        raise ValueError("container_port is required to create a tunnel.")
+    requested_hostname = tunnel.get("url") or None
+    protocol = (tunnel.get("protocol") or "http").lower()
+    ip_address = _resolve_container_ip(proxmox, node, vmid)
+    target_url = f"{protocol}://{ip_address}:{port}"
+    name = tunnel.get("name") or _build_tunnel_name(vmid, port)
+    _stop_cloudflare_process(name)
+    proc, assigned_url = _start_cloudflare_process(name, target_url, hostname=requested_hostname)
+    if not assigned_url:
+        raise RuntimeError("Failed to determine Cloudflare hostname for the tunnel.")
+    updated = {
+        "name": name,
+        "container_port": port,
+        "url": assigned_url,
+        "protocol": protocol,
+        "status": "running",
+        "pid": proc.pid,
+        "target_ip": ip_address,
+        "target_url": target_url,
+        "last_updated": datetime.utcnow().isoformat() + "Z",
+    }
+    _update_container_tunnel(vmid, updated)
+    return updated
+
+
+def _stop_container_tunnel(vmid: int) -> None:
+    try:
+        record = _read_container_record(vmid)
+    except FileNotFoundError:
+        return
+    tunnel = record.get("tunnel")
+    if not tunnel:
+        return
+    name = tunnel.get("name") or _build_tunnel_name(vmid, int(tunnel.get("container_port") or 0))
+    stopped = _stop_cloudflare_process(name)
+    if not stopped and tunnel.get("status") == "stopped":
+        return
+    tunnel_update = {
+        **tunnel,
+        "status": "stopped",
+        "pid": None,
+        "last_updated": datetime.utcnow().isoformat() + "Z",
+    }
+    _update_container_tunnel(vmid, tunnel_update)
+
+
+def _remove_container_tunnel_state(vmid: int) -> None:
+    _stop_container_tunnel(vmid)
+    _update_container_tunnel(vmid, None)
+
+
+def _ensure_container_tunnel_running(proxmox: Any, node: str, vmid: int) -> None:
+    try:
+        record = _read_container_record(vmid)
+    except FileNotFoundError:
+        return
+    tunnel = record.get("tunnel")
+    if not tunnel:
+        return
+    _ensure_cloudflare_token(_load_config())
+    _launch_container_tunnel(proxmox, node, vmid, tunnel)
+
+
 def _build_container_payload(message: Dict[str, Any], config: Dict[str, Any]) -> Dict[str, Any]:
     templates = config.get("templates") or []
     default_template = templates[0] if templates else ""
@@ -707,6 +816,116 @@ def _run_pct_push(vmid: int, src: str, dest: str) -> subprocess.CompletedProcess
     return _call_subprocess(["pct", "push", str(vmid), src, dest])
 
 
+def _build_tunnel_name(vmid: int, port: int) -> str:
+    return f"portacode-ct{vmid}-{port}"
+
+
+def _get_cloudflared_binary() -> str:
+    binary = shutil.which("cloudflared")
+    if not binary:
+        raise RuntimeError(
+            "cloudflared is required for Cloudflare tunnels but was not found on PATH. "
+            "Install cloudflared and run 'cloudflared tunnel login' before creating tunnels."
+        )
+    return binary
+
+
+def _drain_stream(stream: Optional[Any]) -> None:
+    if stream is None:
+        return
+    try:
+        for _ in iter(stream.readline, ""):
+            continue
+    except Exception:
+        pass
+    finally:
+        try:
+            stream.close()
+        except Exception:
+            pass
+
+
+def _await_quick_tunnel_url(proc: subprocess.Popen, timeout: float = 15.0) -> Optional[str]:
+    if not proc.stdout:
+        return None
+    cf_re = re.compile(r"https://[A-Za-z0-9\-.]+\.cfargotunnel\.com")
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        ready, _, _ = select.select([proc.stdout], [], [], 1)
+        if not ready:
+            continue
+        line = proc.stdout.readline()
+        if not line:
+            continue
+        match = cf_re.search(line)
+        if match:
+            return match.group(0)
+    return None
+
+
+def _start_cloudflare_process(name: str, target_url: str, hostname: Optional[str] = None) -> Tuple[subprocess.Popen, Optional[str]]:
+    binary = _get_cloudflared_binary()
+    cmd = [
+        binary,
+        "tunnel",
+        "--url",
+        target_url,
+        "--no-autoupdate",
+    ]
+    if hostname:
+        cmd.extend(["--hostname", hostname])
+        stdout_target = subprocess.DEVNULL
+    else:
+        stdout_target = subprocess.PIPE
+    proc = subprocess.Popen(
+        cmd,
+        stdout=stdout_target,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+    with _CLOUDFLARE_TUNNELS_LOCK:
+        _CLOUDFLARE_TUNNEL_PROCESSES[name] = proc
+    assigned_url = hostname
+    if not hostname:
+        assigned_url = _await_quick_tunnel_url(proc)
+        threading.Thread(target=_drain_stream, args=(proc.stdout,), daemon=True).start()
+    threading.Thread(target=_drain_stream, args=(proc.stderr,), daemon=True).start()
+    return proc, assigned_url
+
+
+def _stop_cloudflare_process(name: str) -> bool:
+    with _CLOUDFLARE_TUNNELS_LOCK:
+        proc = _CLOUDFLARE_TUNNEL_PROCESSES.pop(name, None)
+    if not proc:
+        return False
+    try:
+        proc.terminate()
+        proc.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        proc.wait()
+    return True
+
+
+def _resolve_container_ip(proxmox: Any, node: str, vmid: int) -> str:
+    status = proxmox.nodes(node).lxc(vmid).status.current.get()
+    if status:
+        ip_field = status.get("ip")
+        if isinstance(ip_field, list):
+            for entry in ip_field:
+                if isinstance(entry, str) and "." in entry:
+                    return entry.split("/")[0]
+        elif isinstance(ip_field, str) and "." in ip_field:
+            return ip_field.split("/")[0]
+    res = _run_pct_exec(vmid, ["ip", "-4", "-o", "addr", "show", "eth0"])
+    line = res.stdout.splitlines()[0] if res.stdout else ""
+    parts = line.split()
+    if len(parts) >= 4:
+        addr = parts[3]
+        return addr.split("/")[0]
+    raise RuntimeError("Unable to determine container IP address")
+
+
 def _push_bytes_to_container(
     vmid: int, user: str, path: str, data: bytes, mode: int = 0o600
 ) -> None:
@@ -1091,6 +1310,7 @@ def configure_infrastructure(
     default_storage = _pick_storage(storages)
     templates = _list_templates(client, node, storages)
     network = dict(existing.get("network", {}) or {})
+    _ensure_cloudflared_installed()
     if not network.get("applied"):
         try:
             network = _ensure_bridge()
@@ -1602,6 +1822,10 @@ class StartProxmoxContainerHandler(SyncHandler):
 
         status, elapsed = _start_container(proxmox, node, vmid)
         _update_container_record(vmid, {"status": "running"})
+        try:
+            _ensure_container_tunnel_running(proxmox, node, vmid)
+        except Exception as exc:
+            raise RuntimeError(f"Failed to start Cloudflare tunnel for container {vmid}: {exc}") from exc
 
         infra = get_infra_snapshot()
         return {
@@ -1631,6 +1855,7 @@ class StopProxmoxContainerHandler(SyncHandler):
         _ensure_container_managed(proxmox, node, vmid)
 
         status, elapsed = _stop_container(proxmox, node, vmid)
+        _stop_container_tunnel(vmid)
         final_status = status.get("status") or "stopped"
         _update_container_record(vmid, {"status": final_status})
 
@@ -1666,8 +1891,13 @@ class RemoveProxmoxContainerHandler(SyncHandler):
         node = _get_node_from_config(config)
         _ensure_container_managed(proxmox, node, vmid)
 
+        _stop_container_tunnel(vmid)
         stop_status, stop_elapsed = _stop_container(proxmox, node, vmid)
         delete_status, delete_elapsed = _delete_container(proxmox, node, vmid)
+        try:
+            _update_container_tunnel(vmid, None)
+        except FileNotFoundError:
+            pass
         _remove_container_record(vmid)
 
         infra = get_infra_snapshot()
@@ -1686,6 +1916,107 @@ class RemoveProxmoxContainerHandler(SyncHandler):
         }
 
 
+class CreateCloudflareTunnelHandler(SyncHandler):
+    """Create a Cloudflare tunnel for a container."""
+
+    @property
+    def command_name(self) -> str:
+        return "create_cloudflare_tunnel"
+
+    def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        vmid = _parse_ctid(message)
+        container_port = int(message.get("container_port") or 0)
+        if container_port <= 0:
+            raise ValueError("container_port is required and must be greater than zero.")
+        hostname = (message.get("cloudflare_url") or message.get("hostname") or "").strip()
+        hostname = hostname or None
+        protocol = (message.get("protocol") or "http").strip().lower()
+        if protocol not in {"http", "https", "tcp"}:
+            raise ValueError("protocol must be one of http, https, or tcp.")
+        config = _ensure_infra_configured()
+        _ensure_cloudflare_token(config)
+        proxmox = _connect_proxmox(config)
+        node = _get_node_from_config(config)
+        _ensure_container_managed(proxmox, node, vmid)
+        status = proxmox.nodes(node).lxc(vmid).status.current.get().get("status")
+        if status != "running":
+            raise RuntimeError("Container must be running to create a tunnel.")
+        tunnel = {
+            "container_port": container_port,
+            "protocol": protocol,
+        }
+        if hostname:
+            tunnel["url"] = hostname
+        created = _launch_container_tunnel(proxmox, node, vmid, tunnel)
+        return {
+            "event": "cloudflare_tunnel_created",
+            "ctid": str(vmid),
+            "success": True,
+            "message": f"Created Cloudflare tunnel for container {vmid}.",
+            "tunnel": created,
+        }
+
+
+class UpdateCloudflareTunnelHandler(SyncHandler):
+    """Update an existing Cloudflare tunnel for a container."""
+
+    @property
+    def command_name(self) -> str:
+        return "update_cloudflare_tunnel"
+
+    def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        vmid = _parse_ctid(message)
+        config = _ensure_infra_configured()
+        _ensure_cloudflare_token(config)
+        proxmox = _connect_proxmox(config)
+        node = _get_node_from_config(config)
+        _ensure_container_managed(proxmox, node, vmid)
+        record = _read_container_record(vmid)
+        tunnel = record.get("tunnel")
+        if not tunnel:
+            raise RuntimeError("No Cloudflare tunnel configured for this container.")
+        container_port = int(message.get("container_port") or tunnel.get("container_port") or 0)
+        if container_port <= 0:
+            raise ValueError("container_port must be greater than zero.")
+        hostname = (message.get("cloudflare_url") or tunnel.get("url") or "").strip()
+        hostname = hostname or None
+        protocol = (message.get("protocol") or tunnel.get("protocol") or "http").strip().lower()
+        if protocol not in {"http", "https", "tcp"}:
+            raise ValueError("protocol must be one of http, https, or tcp.")
+        updated_tunnel = {
+            "container_port": container_port,
+            "protocol": protocol,
+        }
+        if hostname:
+            updated_tunnel["url"] = hostname
+        result = _launch_container_tunnel(proxmox, node, vmid, updated_tunnel)
+        return {
+            "event": "cloudflare_tunnel_updated",
+            "ctid": str(vmid),
+            "success": True,
+            "message": f"Updated Cloudflare tunnel for container {vmid}.",
+            "tunnel": result,
+        }
+
+
+class RemoveCloudflareTunnelHandler(SyncHandler):
+    """Remove any Cloudflare tunnel associated with a container."""
+
+    @property
+    def command_name(self) -> str:
+        return "remove_cloudflare_tunnel"
+
+    def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        vmid = _parse_ctid(message)
+        _remove_container_tunnel_state(vmid)
+        return {
+            "event": "cloudflare_tunnel_removed",
+            "ctid": str(vmid),
+            "success": True,
+            "message": f"Removed Cloudflare tunnel state for container {vmid}.",
+        }
+
+
 class ConfigureProxmoxInfraHandler(SyncHandler):
     @property
     def command_name(self) -> str:

{portacode-1.4.15.dev0 → portacode-1.4.15.dev2}/portacode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: portacode
-Version: 1.4.15.dev0
+Version: 1.4.15.dev2
 Summary: Portacode CLI client and SDK
 Home-page: https://github.com/portacode/portacode
 Author: Meena Erian