embedded-lab-control 0.2.0__py3-none-any.whl

labctl/serial/proxy.py

@@ -0,0 +1,802 @@
+"""
+Multi-client serial proxy for lab controller.
+
+Enables multiple clients to simultaneously access a serial console with
+first-writer-wins write lock policy. Includes session logging.
+
+Use cases:
+- Multiple viewers watching console output (read-only)
+- Single writer with multiple readers
+- CLI and web clients viewing same console simultaneously
+"""
+
+import asyncio
+import json
+import logging
+import os
+import socket
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+def _proxy_state_dir(log_dir: Optional[Path]) -> Path:
+    """Return the directory used for persistent proxy state files."""
+    base = log_dir.parent if log_dir else (Path.home() / ".local" / "share" / "labctl")
+    return base / "proxy-state"
+
+
+def _proxy_state_path(name: str, log_dir: Optional[Path]) -> Path:
+    """Return the state-file path for a named proxy."""
+    return _proxy_state_dir(log_dir) / f"{name}.json"
+
+
+def _pid_is_alive(pid: int) -> bool:
+    """Return True when the process is still alive."""
+    try:
+        os.kill(pid, 0)
+    except PermissionError:
+        return True
+    except OSError:
+        return False
+    return True
+
+
+def write_proxy_state(
+    *,
+    name: str,
+    log_dir: Optional[Path],
+    proxy_port: int,
+    ser2net_port: int,
+    allow_write: bool,
+) -> Path:
+    """Persist a foreground proxy's runtime metadata for other processes."""
+    state_dir = _proxy_state_dir(log_dir)
+    state_dir.mkdir(parents=True, exist_ok=True)
+    path = _proxy_state_path(name, log_dir)
+    payload = {
+        "name": name,
+        "pid": os.getpid(),
+        "proxy_port": proxy_port,
+        "ser2net_port": ser2net_port,
+        "allow_write": allow_write,
+        "started_at": datetime.now().isoformat(),
+    }
+    path.write_text(json.dumps(payload, indent=2))
+    return path
+
+
+def remove_proxy_state(name: str, log_dir: Optional[Path]) -> None:
+    """Remove a proxy state file if present."""
+    path = _proxy_state_path(name, log_dir)
+    try:
+        path.unlink()
+    except FileNotFoundError:
+        pass
+
+
+def read_proxy_state(name: str, log_dir: Optional[Path]) -> Optional[dict]:
+    """Read proxy state for an SBC, pruning stale files automatically."""
+    path = _proxy_state_path(name, log_dir)
+    if not path.exists():
+        return None
+
+    try:
+        payload = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return None
+
+    pid = payload.get("pid")
+    if not isinstance(pid, int) or not _pid_is_alive(pid):
+        remove_proxy_state(name, log_dir)
+        return None
+
+    return payload
+
+
+@dataclass
+class ProxyClient:
+    """Represents a connected proxy client."""
+
+    client_id: str
+    reader: asyncio.StreamReader
+    writer: asyncio.StreamWriter
+    connected_at: datetime = field(default_factory=datetime.now)
+    last_activity: datetime = field(default_factory=datetime.now)
+    has_write_lock: bool = False
+
+    @property
+    def address(self) -> str:
+        """Get client address as string."""
+        try:
+            peername = self.writer.get_extra_info("peername")
+            if peername:
+                return f"{peername[0]}:{peername[1]}"
+        except Exception:
+            pass
+        return "unknown"
+
+
+class LogRotator:
+    """Manages log rotation for session logs.
+
+    Rotates logs based on:
+    - Size (max_size_mb)
+    - Age (max_age_days)
+    """
+
+    def __init__(
+        self,
+        log_dir: Path,
+        max_size_mb: float = 10.0,
+        max_age_days: int = 30,
+        compress: bool = True,
+    ):
+        self.log_dir = log_dir
+        self.max_size_bytes = int(max_size_mb * 1024 * 1024)
+        self.max_age_days = max_age_days
+        self.compress = compress
+
+    def should_rotate(self, log_file: Path) -> bool:
+        """Check if log file should be rotated based on size."""
+        if not log_file.exists():
+            return False
+        return log_file.stat().st_size >= self.max_size_bytes
+
+    def rotate(self, log_file: Path) -> Optional[Path]:
+        """Rotate a log file.
+
+        Renames current log to .1, compresses old rotated logs.
+        Returns path to rotated file or None if no rotation needed.
+        """
+        import gzip
+        import shutil
+
+        if not log_file.exists():
+            return None
+
+        # Find next rotation number
+        base = log_file.stem
+        suffix = log_file.suffix
+
+        for i in range(99, 0, -1):
+            old_path = self.log_dir / f"{base}.{i}{suffix}"
+            new_path = self.log_dir / f"{base}.{i + 1}{suffix}"
+            old_gz = self.log_dir / f"{base}.{i}{suffix}.gz"
+            new_gz = self.log_dir / f"{base}.{i + 1}{suffix}.gz"
+
+            if old_gz.exists():
+                if i + 1 <= 99:
+                    shutil.move(old_gz, new_gz)
+            elif old_path.exists():
+                if i + 1 <= 99:
+                    shutil.move(old_path, new_path)
+
+        # Rotate current to .1
+        rotated = self.log_dir / f"{base}.1{suffix}"
+        shutil.move(log_file, rotated)
+
+        # Compress rotated log
+        if self.compress:
+            with open(rotated, "rb") as f_in:
+                with gzip.open(f"{rotated}.gz", "wb") as f_out:
+                    shutil.copyfileobj(f_in, f_out)
+            rotated.unlink()
+            rotated = Path(f"{rotated}.gz")
+
+        return rotated
+
+    def cleanup_old_logs(self) -> int:
+        """Remove logs older than max_age_days.
+
+        Returns number of files deleted.
+        """
+        import time
+
+        if not self.log_dir.exists():
+            return 0
+
+        cutoff_time = time.time() - (self.max_age_days * 24 * 60 * 60)
+        deleted = 0
+
+        for log_file in self.log_dir.glob("*.log*"):
+            try:
+                if log_file.stat().st_mtime < cutoff_time:
+                    log_file.unlink()
+                    deleted += 1
+                    logger.debug(f"Deleted old log: {log_file}")
+            except Exception as e:
+                logger.warning(f"Failed to delete {log_file}: {e}")
+
+        return deleted
+
+
+class SessionLogger:
+    """Logs all serial traffic to timestamped files.
+
+    Supports log rotation based on size and cleanup of old logs.
+    """
+
+    def __init__(
+        self,
+        log_dir: Path,
+        session_name: str,
+        max_size_mb: float = 10.0,
+        max_age_days: int = 30,
+    ):
+        self.log_dir = log_dir
+        self.session_name = session_name
+        self.log_file: Optional[Path] = None
+        self._file_handle = None
+        self._rotator = LogRotator(
+            log_dir,
+            max_size_mb=max_size_mb,
+            max_age_days=max_age_days,
+        )
+        self._bytes_written = 0
+
+    def start(self) -> Path:
+        """Start logging session, returns log file path."""
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+
+        # Cleanup old logs on start
+        deleted = self._rotator.cleanup_old_logs()
+        if deleted > 0:
+            logger.info(f"Cleaned up {deleted} old log files")
+
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f")[:-3]
+        self.log_file = self.log_dir / f"{self.session_name}_{timestamp}.log"
+        self._bytes_written = 0
+
+        self._file_handle = open(self.log_file, "a", buffering=1)  # Line buffered
+        self._write_header()
+        return self.log_file
+
+    def _write_header(self) -> None:
+        """Write session header to log file."""
+        if self._file_handle:
+            self._file_handle.write(f"# Session: {self.session_name}\n")
+            self._file_handle.write(f"# Started: {datetime.now().isoformat()}\n")
+            self._file_handle.write("# Format: [timestamp] [direction] data\n")
+            self._file_handle.write("# Direction: >> = from device, << = to device\n")
+            self._file_handle.write("#" + "=" * 60 + "\n")
+
+    def _check_rotation(self) -> None:
+        """Check if rotation is needed and perform if so."""
+        if self.log_file and self._rotator.should_rotate(self.log_file):
+            # Close current file
+            if self._file_handle:
+                self._file_handle.close()
+                self._file_handle = None
+
+            try:
+                # Rotate
+                rotated = self._rotator.rotate(self.log_file)
+                logger.info(f"Rotated log to {rotated}")
+
+                # Start new file
+                timestamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f")[:-3]
+                self.log_file = self.log_dir / f"{self.session_name}_{timestamp}.log"
+                self._file_handle = open(self.log_file, "a", buffering=1)
+                self._write_header()
+                self._bytes_written = 0
+            except Exception as e:
+                logger.error(f"Log rotation failed: {e}")
+                # _file_handle remains None; subsequent log calls are no-ops
+
+    def log_output(self, data: bytes) -> None:
+        """Log data received from device (output)."""
+        if self._file_handle:
+            timestamp = datetime.now().strftime("%H:%M:%S.%f")[:-3]
+            # Escape non-printable bytes for readability
+            text = data.decode("utf-8", errors="replace")
+            line = f"[{timestamp}] >> {repr(text)}\n"
+            self._file_handle.write(line)
+            self._bytes_written += len(line.encode())
+            self._check_rotation()
+
+    def log_input(self, data: bytes, client_id: str) -> None:
+        """Log data sent to device (input)."""
+        if self._file_handle:
+            timestamp = datetime.now().strftime("%H:%M:%S.%f")[:-3]
+            text = data.decode("utf-8", errors="replace")
+            line = f"[{timestamp}] << [{client_id[:8]}] {repr(text)}\n"
+            self._file_handle.write(line)
+            self._bytes_written += len(line.encode())
+            self._check_rotation()
+
+    def stop(self) -> None:
+        """Stop logging session."""
+        if self._file_handle:
+            self._file_handle.write("#" + "=" * 60 + "\n")
+            self._file_handle.write(f"# Ended: {datetime.now().isoformat()}\n")
+            self._file_handle.close()
+            self._file_handle = None
+
+
+class SerialProxy:
+    """
+    Multi-client serial proxy with first-writer-wins policy.
+
+    Connects to ser2net TCP port and allows multiple clients to:
+    - Read all console output (broadcast to all)
+    - Write to console (first client to write gets exclusive lock)
+    """
+
+    def __init__(
+        self,
+        name: str,
+        ser2net_host: str,
+        ser2net_port: int,
+        proxy_port: int,
+        log_dir: Optional[Path] = None,
+        write_policy: str = "first",
+        max_clients: int = 10,
+        allow_write: bool = False,
+        reconnect_on_disconnect: bool = True,
+        reconnect_delay: float = 1.0,
+    ):
+        """
+        Initialize serial proxy.
+
+        Args:
+            name: Name for this proxy session (e.g., SBC name)
+            ser2net_host: Host where ser2net is running
+            ser2net_port: TCP port of ser2net connection
+            proxy_port: Port this proxy listens on
+            log_dir: Directory for session logs (None to disable)
+            write_policy: Write policy - "first", "all", or "queue"
+            max_clients: Maximum concurrent clients
+            allow_write: Whether proxy clients may write upstream
+            reconnect_on_disconnect: Reconnect after upstream serial drops
+            reconnect_delay: Seconds to wait between reconnect attempts
+        """
+        self.name = name
+        self.ser2net_host = ser2net_host
+        self.ser2net_port = ser2net_port
+        self.proxy_port = proxy_port
+        self.log_dir = log_dir
+        self.write_policy = write_policy
+        self.max_clients = max_clients
+        self.allow_write = allow_write
+        self.reconnect_on_disconnect = reconnect_on_disconnect
+        self.reconnect_delay = reconnect_delay
+
+        self.clients: dict[str, ProxyClient] = {}
+        self.writer_client_id: Optional[str] = None
+        self._lock = asyncio.Lock()
+        self._server: Optional[asyncio.Server] = None
+        self._ser2net_reader: Optional[asyncio.StreamReader] = None
+        self._ser2net_writer: Optional[asyncio.StreamWriter] = None
+        self._running = False
+        self._read_task: Optional[asyncio.Task] = None
+        self._session_logger: Optional[SessionLogger] = None
+        self._stopping = False
+
+    @property
+    def client_count(self) -> int:
+        """Return number of connected clients."""
+        return len(self.clients)
+
+    @property
+    def is_running(self) -> bool:
+        """Check if proxy is running."""
+        return self._running
+
+    async def start(self) -> None:
+        """Start the proxy server."""
+        if self._running:
+            raise RuntimeError("Proxy already running")
+
+        await self._connect_upstream()
+
+        # Start session logger
+        if self.log_dir:
+            self._session_logger = SessionLogger(self.log_dir, self.name)
+            log_file = self._session_logger.start()
+            logger.info(f"Session logging to {log_file}")
+
+        # Start proxy server
+        self._server = await asyncio.start_server(
+            self._handle_client,
+            "127.0.0.1",
+            self.proxy_port,
+        )
+        self._running = True
+        write_proxy_state(
+            name=self.name,
+            log_dir=self.log_dir,
+            proxy_port=self.proxy_port,
+            ser2net_port=self.ser2net_port,
+            allow_write=self.allow_write,
+        )
+
+        # Start reading from ser2net
+        self._read_task = asyncio.create_task(self._read_serial_loop())
+
+        logger.info(f"Proxy '{self.name}' started on port {self.proxy_port}")
+
+    async def stop(self) -> None:
+        """Stop the proxy server gracefully."""
+        if self._stopping:
+            return
+        if (
+            not self._running
+            and self._server is None
+            and self._ser2net_writer is None
+            and self._read_task is None
+        ):
+            return
+
+        self._stopping = True
+        self._running = False
+        logger.info(f"Stopping proxy '{self.name}'")
+        remove_proxy_state(self.name, self.log_dir)
+
+        # Cancel read task
+        current_task = asyncio.current_task()
+        if self._read_task and self._read_task is not current_task:
+            self._read_task.cancel()
+            try:
+                await self._read_task
+            except asyncio.CancelledError:
+                pass
+        self._read_task = None
+
+        # Disconnect all clients
+        for client in list(self.clients.values()):
+            await self._disconnect_client(client, "Proxy shutting down")
+
+        await self._close_upstream()
+
+        # Stop server
+        if self._server:
+            self._server.close()
+            await self._server.wait_closed()
+            self._server = None
+
+        # Stop session logger
+        if self._session_logger:
+            self._session_logger.stop()
+            self._session_logger = None
+
+        logger.info(f"Proxy '{self.name}' stopped")
+        self._stopping = False
+
+    async def _connect_upstream(self) -> None:
+        """Connect to the upstream ser2net TCP socket."""
+        logger.info(f"Connecting to ser2net at {self.ser2net_host}:{self.ser2net_port}")
+        try:
+            self._ser2net_reader, self._ser2net_writer = await asyncio.open_connection(
+                self.ser2net_host, self.ser2net_port
+            )
+        except Exception as e:
+            host_port = f"{self.ser2net_host}:{self.ser2net_port}"
+            raise ConnectionError(f"Failed to connect to ser2net at {host_port}: {e}")
+
+    async def _close_upstream(self) -> None:
+        """Close the upstream ser2net TCP connection."""
+        writer = self._ser2net_writer
+        self._ser2net_reader = None
+        self._ser2net_writer = None
+        if writer:
+            writer.close()
+            try:
+                await writer.wait_closed()
+            except Exception:
+                pass
+
+    async def _broadcast_notice(self, message: str) -> None:
+        """Broadcast a proxy status line to all connected clients."""
+        if not self.clients:
+            return
+        await self._broadcast(f"\r\n[Proxy: {message}]\r\n".encode())
+
+    async def _handle_upstream_disconnect(self, reason: str) -> bool:
+        """Handle loss of the upstream serial connection.
+
+        Returns True if the proxy should keep running and try to reconnect.
+        """
+        logger.warning(reason)
+        await self._close_upstream()
+
+        if not self._running:
+            return False
+
+        if not self.reconnect_on_disconnect:
+            logger.error("ser2net connection lost, stopping proxy")
+            asyncio.create_task(self.stop())
+            return False
+
+        await self._broadcast_notice("Serial connection lost; retrying...")
+        return True
+
+    async def _handle_client(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        """Handle a new client connection."""
+        client_id = str(uuid.uuid4())
+        client = ProxyClient(
+            client_id=client_id,
+            reader=reader,
+            writer=writer,
+        )
+
+        # Check max clients
+        if len(self.clients) >= self.max_clients:
+            logger.warning(f"Rejecting client {client_id}: max clients reached")
+            writer.write(
+                b"\r\n[Proxy: Maximum clients reached, connection refused]\r\n"
+            )
+            await writer.drain()
+            writer.close()
+            return
+
+        self.clients[client_id] = client
+        logger.info(f"Client {client_id[:8]} connected from {client.address}")
+
+        # Send welcome message
+        writer.write(f"\r\n[Proxy: Connected to {self.name}".encode())
+        if not self.allow_write:
+            writer.write(b" (read-only)]")
+        elif self.writer_client_id:
+            writer.write(b" (read-only, another client has write lock)]")
+        else:
+            writer.write(b" (you have write access)]")
+        writer.write(b"\r\n")
+        await writer.drain()
+
+        try:
+            await self._client_read_loop(client)
+        except Exception as e:
+            logger.debug(f"Client {client_id[:8]} error: {e}")
+        finally:
+            await self._disconnect_client(client, "Client disconnected")
+
+    async def _client_read_loop(self, client: ProxyClient) -> None:
+        """Read data from client and forward to serial if allowed."""
+        while self._running:
+            try:
+                data = await asyncio.wait_for(client.reader.read(1024), timeout=1.0)
+                if not data:
+                    break  # Client disconnected
+
+                client.last_activity = datetime.now()
+
+                # Check write permission
+                if not self._can_write(client.client_id):
+                    if not self.allow_write:
+                        continue  # Read-only proxy: silently ignore client input
+                    # Try to acquire write lock (atomic via asyncio.Lock)
+                    async with self._lock:
+                        if self.writer_client_id is None:
+                            self.writer_client_id = client.client_id
+                            client.has_write_lock = True
+                    if client.has_write_lock:
+                        logger.info(
+                            f"Client {client.client_id[:8]} acquired write lock"
+                        )
+                        client.writer.write(
+                            b"\r\n[Proxy: You now have write access]\r\n"
+                        )
+                        await client.writer.drain()
+                    else:
+                        continue  # Silently drop the write
+
+                # Forward to ser2net
+                if self._ser2net_writer and self._can_write(client.client_id):
+                    self._ser2net_writer.write(data)
+                    await self._ser2net_writer.drain()
+
+                    # Log input
+                    if self._session_logger:
+                        self._session_logger.log_input(data, client.client_id)
+
+            except asyncio.TimeoutError:
+                continue
+            except Exception as e:
+                logger.debug(f"Client read error: {e}")
+                break
+
+    def _can_write(self, client_id: str) -> bool:
+        """Check if client can write based on policy."""
+        if not self.allow_write:
+            return False
+        if self.write_policy == "all":
+            return True
+        elif self.write_policy == "first":
+            return self.writer_client_id is None or self.writer_client_id == client_id
+        else:
+            # queue policy - not implemented yet
+            return self.writer_client_id is None or self.writer_client_id == client_id
+
+    async def _read_serial_loop(self) -> None:
+        """Read from ser2net and broadcast to all clients."""
+        while self._running:
+            if self._ser2net_reader is None:
+                try:
+                    await self._connect_upstream()
+                except ConnectionError as e:
+                    logger.warning(f"Reconnect to ser2net failed: {e}")
+                    await asyncio.sleep(self.reconnect_delay)
+                    continue
+
+                logger.info("ser2net connection restored")
+                await self._broadcast_notice("Serial connection restored")
+
+            try:
+                data = await asyncio.wait_for(
+                    self._ser2net_reader.read(4096), timeout=1.0
+                )
+                if not data:
+                    should_retry = await self._handle_upstream_disconnect(
+                        "ser2net connection closed"
+                    )
+                    if not should_retry:
+                        break
+                    await asyncio.sleep(self.reconnect_delay)
+                    continue
+
+                # Log output
+                if self._session_logger:
+                    self._session_logger.log_output(data)
+
+                # Broadcast to all clients
+                await self._broadcast(data)
+
+            except asyncio.TimeoutError:
+                continue
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                should_retry = await self._handle_upstream_disconnect(
+                    f"Serial read error: {e}"
+                )
+                if not should_retry:
+                    break
+                await asyncio.sleep(self.reconnect_delay)
+
+    async def _broadcast(self, data: bytes) -> None:
+        """Send data to all connected clients."""
+        disconnected = []
+
+        for client_id, client in list(self.clients.items()):
+            try:
+                client.writer.write(data)
+                await client.writer.drain()
+            except Exception as e:
+                logger.debug(f"Failed to send to client {client_id[:8]}: {e}")
+                disconnected.append(client)
+
+        # Clean up disconnected clients
+        for client in disconnected:
+            await self._disconnect_client(client, "Write failed")
+
+    async def _disconnect_client(self, client: ProxyClient, reason: str) -> None:
+        """Disconnect a client and clean up."""
+        client_id = client.client_id
+
+        if client_id not in self.clients:
+            return
+
+        del self.clients[client_id]
+
+        # Release write lock if this client had it
+        if self.writer_client_id == client_id:
+            self.writer_client_id = None
+            logger.info(f"Write lock released by {client_id[:8]}")
+
+        try:
+            client.writer.close()
+            await client.writer.wait_closed()
+        except Exception:
+            pass
+
+        logger.info(f"Client {client_id[:8]} disconnected: {reason}")
+
+    def get_clients_info(self) -> list[dict]:
+        """Get information about connected clients."""
+        return [
+            {
+                "client_id": c.client_id,
+                "address": c.address,
+                "connected_at": c.connected_at.isoformat(),
+                "has_write_lock": c.has_write_lock,
+            }
+            for c in self.clients.values()
+        ]
+
+
+class ProxyManager:
+    """Manages multiple serial proxy instances."""
+
+    def __init__(self, log_dir: Optional[Path] = None):
+        self.proxies: dict[str, SerialProxy] = {}
+        self.log_dir = log_dir
+        self._port_counter = 5500
+
+    @staticmethod
+    def _port_is_available(port: int, host: str = "127.0.0.1") -> bool:
+        """Return True if the TCP port can be bound on the given host."""
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            try:
+                sock.bind((host, port))
+            except OSError:
+                return False
+        return True
+
+    def get_next_port(self, base: int = 5500, range_size: int = 100) -> int:
+        """Get next available proxy port."""
+        used_ports = {p.proxy_port for p in self.proxies.values()}
+        for port in range(base, base + range_size):
+            if port not in used_ports and self._port_is_available(port):
+                return port
+        raise RuntimeError("No available proxy ports")
+
+    async def create_proxy(
+        self,
+        name: str,
+        ser2net_host: str,
+        ser2net_port: int,
+        proxy_port: Optional[int] = None,
+        write_policy: str = "first",
+        max_clients: int = 10,
+        allow_write: bool = False,
+    ) -> SerialProxy:
+        """Create and start a new proxy."""
+        if name in self.proxies:
+            raise ValueError(f"Proxy '{name}' already exists")
+
+        if proxy_port is None:
+            proxy_port = self.get_next_port()
+
+        proxy = SerialProxy(
+            name=name,
+            ser2net_host=ser2net_host,
+            ser2net_port=ser2net_port,
+            proxy_port=proxy_port,
+            log_dir=self.log_dir,
+            write_policy=write_policy,
+            max_clients=max_clients,
+            allow_write=allow_write,
+        )
+
+        await proxy.start()
+        self.proxies[name] = proxy
+        return proxy
+
+    async def stop_proxy(self, name: str) -> bool:
+        """Stop and remove a proxy."""
+        if name not in self.proxies:
+            return False
+
+        proxy = self.proxies.pop(name)
+        await proxy.stop()
+        return True
+
+    async def stop_all(self) -> None:
+        """Stop all proxies."""
+        for name in list(self.proxies.keys()):
+            await self.stop_proxy(name)
+
+    def get_proxy(self, name: str) -> Optional[SerialProxy]:
+        """Get a proxy by name."""
+        return self.proxies.get(name)
+
+    def list_proxies(self) -> list[dict]:
+        """List all active proxies."""
+        return [
+            {
+                "name": p.name,
+                "proxy_port": p.proxy_port,
+                "ser2net_port": p.ser2net_port,
+                "client_count": p.client_count,
+                "writer_client": p.writer_client_id[:8] if p.writer_client_id else None,
+            }
+            for p in self.proxies.values()
+        ]