nps-ctl 0.1.0__py3-none-any.whl

nps_ctl/__init__.py

@@ -0,0 +1,35 @@
+"""nps-ctl: A Python library and CLI tool for managing NPS servers.
+
+This package provides:
+- NPSClient: API client for a single NPS server
+- NPSCluster: Manager for multiple NPS servers
+- Modular API functions: client_mgmt, tunnel, host
+- CLI tool for command-line management
+- Enhanced logging with configure_logging
+
+Modules:
+    base: NPSClient class (authentication and HTTP requests)
+    cluster: NPSCluster class (multi-server management)
+    client_mgmt: NPC client management functions
+    tunnel: Tunnel management functions
+    host: Host (domain) management functions
+    types: Type definitions (ClientInfo, TunnelInfo, HostInfo, EdgeConfig)
+    exceptions: Exception classes (NPSError, NPSAuthError, NPSAPIError)
+    deploy: Deployment functions (install, uninstall via SSH)
+    utils: Utility functions (auth key generation)
+    logging: Logging configuration and utilities
+"""
+
+__version__ = "0.1.0"
+
+from .base import NPSClient
+from .cluster import NPSCluster
+from .logging import configure_logging, set_log_level
+
+__all__ = [
+    "NPSClient",
+    "NPSCluster",
+    "__version__",
+    "configure_logging",
+    "set_log_level",
+]

nps_ctl/api.py

@@ -0,0 +1,31 @@
+"""NPS API client for managing NPS servers.
+
+This module re-exports all public API components for backward compatibility.
+New code should import directly from the specific modules:
+
+- ``nps_ctl.base`` - NPSClient (API client for a single NPS server)
+- ``nps_ctl.cluster`` - NPSCluster (multi-server management)
+- ``nps_ctl.client_mgmt`` - NPC client management functions
+- ``nps_ctl.tunnel`` - Tunnel management functions
+- ``nps_ctl.host`` - Host (domain) management functions
+- ``nps_ctl.types`` - Type definitions (ClientInfo, TunnelInfo, HostInfo, EdgeConfig)
+- ``nps_ctl.exceptions`` - Exception classes (NPSError, NPSAuthError, NPSAPIError)
+"""
+
+# Re-export everything for backward compatibility
+from .base import NPSClient
+from .cluster import NPSCluster
+from .exceptions import NPSAPIError, NPSAuthError, NPSError
+from .types import ClientInfo, EdgeConfig, HostInfo, TunnelInfo
+
+__all__ = [
+    "ClientInfo",
+    "EdgeConfig",
+    "HostInfo",
+    "NPSAPIError",
+    "NPSAuthError",
+    "NPSClient",
+    "NPSCluster",
+    "NPSError",
+    "TunnelInfo",
+]

nps_ctl/base.py

@@ -0,0 +1,326 @@
+"""Base NPS API client with authentication and request infrastructure.
+
+This module provides the core NPSClient class that handles authentication,
+HTTP requests, and SSL configuration for communicating with NPS servers.
+"""
+
+import hashlib
+import json
+import logging
+import socket
+import ssl
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any
+
+try:
+    import socks
+
+    HAS_SOCKS = True
+except ImportError:
+    HAS_SOCKS = False
+
+from .exceptions import NPSAPIError, NPSAuthError
+from .logging import get_operation_logger
+
+logger = logging.getLogger(__name__)
+op_logger = get_operation_logger(__name__)
+
+
+@dataclass
+class NPSClient:
+    """API client for a single NPS server.
+
+    Provides authenticated HTTP communication with an NPS server's Web API.
+    Domain-specific operations (client management, tunnel management, host
+    management) are provided by separate modules that operate on an
+    NPSClient instance.
+
+    Args:
+        base_url: The base URL of the NPS server (e.g., "https://nps.example.com").
+        auth_key: The authentication key configured in nps.conf.
+        timeout: Request timeout in seconds.
+        verify_ssl: Whether to verify SSL certificates.
+        proxy: HTTP/HTTPS proxy URL (e.g., "http://127.0.0.1:7890").
+        socks_proxy: SOCKS5 proxy address (e.g., "localhost:1080" for SSH tunnel).
+
+    Example:
+        >>> from nps_ctl.base import NPSClient
+        >>> from nps_ctl.client_mgmt import list_clients
+        >>> nps = NPSClient("https://nps.example.com", "your_auth_key")
+        >>> clients = list_clients(nps)
+        >>> for c in clients:
+        ...     print(f"{c['Id']}: {c['Remark']}")
+    """
+
+    base_url: str
+    auth_key: str
+    timeout: int = 30
+    verify_ssl: bool = True
+    max_retries: int = 3
+    retry_backoff: float = 1.0
+    proxy: str | None = None
+    socks_proxy: str | None = None
+    _ssl_context: ssl.SSLContext | None = field(default=None, init=False, repr=False)
+    _opener: urllib.request.OpenerDirector | None = field(
+        default=None, init=False, repr=False
+    )
+    _original_socket: type | None = field(default=None, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        """Initialize SSL context and proxy handler."""
+        self.base_url = self.base_url.rstrip("/")
+
+        # Setup SSL context
+        if not self.verify_ssl:
+            self._ssl_context = ssl.create_default_context()
+            self._ssl_context.check_hostname = False
+            self._ssl_context.verify_mode = ssl.CERT_NONE
+            logger.debug(f"SSL verification disabled for {self.base_url}")
+        else:
+            self._ssl_context = ssl.create_default_context()
+
+        # Setup SOCKS proxy if specified (takes precedence over HTTP proxy)
+        if self.socks_proxy:
+            if not HAS_SOCKS:
+                raise ImportError(
+                    "PySocks is required for SOCKS proxy support. "
+                    "Install it with: pip install PySocks"
+                )
+            # Parse socks_proxy address (format: host:port)
+            if ":" in self.socks_proxy:
+                socks_host, socks_port_str = self.socks_proxy.rsplit(":", 1)
+                socks_port = int(socks_port_str)
+            else:
+                socks_host = self.socks_proxy
+                socks_port = 1080  # Default SOCKS port
+
+            op_logger.connection_attempt(
+                self.base_url,
+                proxy=f"socks5://{socks_host}:{socks_port}",
+                verify_ssl=self.verify_ssl,
+            )
+
+            # Store original socket class for potential cleanup
+            self._original_socket = socket.socket
+
+            # Set default SOCKS proxy globally for this client
+            socks.set_default_proxy(socks.SOCKS5, socks_host, socks_port)
+            socket.socket = socks.socksocket  # type: ignore[assignment]  # runtime monkey-patch for SOCKS proxy
+
+            logger.info(
+                f"SOCKS5 proxy enabled: {socks_host}:{socks_port} for {self.base_url}"
+            )
+
+        # Setup HTTP proxy if specified (only if SOCKS proxy is not set)
+        elif self.proxy:
+            op_logger.connection_attempt(
+                self.base_url, proxy=self.proxy, verify_ssl=self.verify_ssl
+            )
+            proxy_handler = urllib.request.ProxyHandler(
+                {"http": self.proxy, "https": self.proxy}
+            )
+            https_handler = urllib.request.HTTPSHandler(context=self._ssl_context)
+            self._opener = urllib.request.build_opener(proxy_handler, https_handler)
+        else:
+            op_logger.connection_attempt(
+                self.base_url, verify_ssl=self.verify_ssl, timeout=self.timeout
+            )
+
+        logger.info(f"NPSClient initialized for {self.base_url}")
+
+    def _request_with_retry(
+        self,
+        req: urllib.request.Request,
+        *,
+        error_prefix: str = "Request failed",
+        error_cls: type[Exception] = NPSAPIError,
+    ) -> bytes:
+        """Execute an HTTP request with retry and exponential backoff.
+
+        Args:
+            req: The prepared urllib Request object.
+            error_prefix: Prefix for error messages.
+            error_cls: Exception class to raise on final failure.
+
+        Returns:
+            Raw response bytes.
+
+        Raises:
+            error_cls: If all retries are exhausted.
+        """
+        last_error: Exception | None = None
+        url = req.full_url
+        method = req.get_method()
+        start_time = time.perf_counter()
+
+        logger.debug(f"Request: {method} {url}")
+
+        for attempt in range(self.max_retries):
+            attempt_start = time.perf_counter()
+            try:
+                if self._opener:
+                    with self._opener.open(req, timeout=self.timeout) as response:
+                        data = response.read()
+                        elapsed_ms = (time.perf_counter() - attempt_start) * 1000
+                        op_logger.connection_success(url, response_time_ms=elapsed_ms)
+                        logger.debug(
+                            f"Response: {response.status} ({len(data)} bytes, "
+                            f"{elapsed_ms:.1f}ms)"
+                        )
+                        return data
+                else:
+                    with urllib.request.urlopen(
+                        req, timeout=self.timeout, context=self._ssl_context
+                    ) as response:
+                        data = response.read()
+                        elapsed_ms = (time.perf_counter() - attempt_start) * 1000
+                        op_logger.connection_success(url, response_time_ms=elapsed_ms)
+                        logger.debug(
+                            f"Response: {response.status} ({len(data)} bytes, "
+                            f"{elapsed_ms:.1f}ms)"
+                        )
+                        return data
+            except urllib.error.HTTPError as e:
+                last_error = e
+                op_logger.connection_failed(
+                    url, f"HTTP {e.code} {e.reason}", attempt=attempt + 1
+                )
+                if attempt < self.max_retries - 1:
+                    wait = self.retry_backoff * (2**attempt)
+                    logger.info(f"Retrying in {wait:.1f}s...")
+                    time.sleep(wait)
+            except urllib.error.URLError as e:
+                last_error = e
+                op_logger.connection_failed(url, str(e.reason), attempt=attempt + 1)
+                if attempt < self.max_retries - 1:
+                    wait = self.retry_backoff * (2**attempt)
+                    logger.info(f"Retrying in {wait:.1f}s...")
+                    time.sleep(wait)
+            except (TimeoutError, OSError) as e:
+                # Handle socket timeout and other OS-level network errors
+                last_error = e
+                error_msg = "Timeout" if isinstance(e, TimeoutError) else str(e)
+                op_logger.connection_failed(url, error_msg, attempt=attempt + 1)
+                if attempt < self.max_retries - 1:
+                    wait = self.retry_backoff * (2**attempt)
+                    logger.info(f"Retrying in {wait:.1f}s...")
+                    time.sleep(wait)
+
+        # All retries exhausted
+        total_elapsed_ms = (time.perf_counter() - start_time) * 1000
+        logger.error(
+            f"{error_prefix} after {self.max_retries} attempts "
+            f"({total_elapsed_ms:.1f}ms total): {last_error}"
+        )
+        raise error_cls(f"{error_prefix}: {last_error}") from last_error
+
+    def _get_server_time(self) -> int:
+        """Get the server timestamp for authentication.
+
+        Returns:
+            Server timestamp as integer.
+
+        Raises:
+            NPSAuthError: If failed to get server time.
+        """
+        url = f"{self.base_url}/auth/gettime"
+        logger.debug(f"Getting server time from {url}")
+        req = urllib.request.Request(url)
+        try:
+            raw = self._request_with_retry(
+                req,
+                error_prefix="Failed to get server time",
+                error_cls=NPSAuthError,
+            )
+            data = json.loads(raw.decode("utf-8"))
+            return int(data.get("time", 0))
+        except NPSAuthError:
+            raise
+        except (json.JSONDecodeError, ValueError) as e:
+            raise NPSAuthError(f"Invalid server time response: {e}") from e
+
+    def _generate_auth_key(self, timestamp: int) -> str:
+        """Generate authentication key using MD5.
+
+        Args:
+            timestamp: Server timestamp.
+
+        Returns:
+            MD5 hash of auth_key + timestamp.
+        """
+        raw = f"{self.auth_key}{timestamp}"
+        return hashlib.md5(raw.encode("utf-8")).hexdigest()
+
+    def request(
+        self,
+        endpoint: str,
+        method: str = "GET",
+        data: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Make an authenticated API request.
+
+        Args:
+            endpoint: API endpoint (e.g., "/client/list").
+            method: HTTP method.
+            data: Request data for POST requests.
+
+        Returns:
+            JSON response as dictionary.
+
+        Raises:
+            NPSAPIError: If the request fails.
+        """
+        start_time = time.perf_counter()
+        op_logger.request_start(method, endpoint, data)
+
+        timestamp = self._get_server_time()
+        auth_key = self._generate_auth_key(timestamp)
+
+        # Auth params must be included in POST body, not URL query string
+        auth_params = {"auth_key": auth_key, "timestamp": str(timestamp)}
+
+        if method == "POST":
+            # For POST requests, include auth params in the body
+            post_params = {**auth_params}
+            if data:
+                post_params.update({k: str(v) for k, v in data.items()})
+            post_data = urllib.parse.urlencode(post_params).encode("utf-8")
+            url = f"{self.base_url}{endpoint}"
+            req = urllib.request.Request(url, data=post_data, method="POST")
+            req.add_header("Content-Type", "application/x-www-form-urlencoded")
+        else:
+            # For GET requests, include auth params in URL
+            params = {**auth_params}
+            if data:
+                params.update({k: str(v) for k, v in data.items()})
+            url = f"{self.base_url}{endpoint}?{urllib.parse.urlencode(params)}"
+            req = urllib.request.Request(url, method=method)
+
+        try:
+            raw = self._request_with_retry(
+                req,
+                error_prefix=f"API request {endpoint} failed",
+            )
+            response_data = raw.decode("utf-8")
+            result = json.loads(response_data)
+            elapsed_ms = (time.perf_counter() - start_time) * 1000
+            api_status = result.get("status")
+            op_logger.request_success(
+                method, endpoint, status=api_status, response_time_ms=elapsed_ms
+            )
+            return result
+
+        except NPSAPIError as e:
+            elapsed_ms = (time.perf_counter() - start_time) * 1000
+            op_logger.request_failed(
+                method, endpoint, str(e), status_code=getattr(e, "status_code", None)
+            )
+            raise
+        except json.JSONDecodeError as e:
+            elapsed_ms = (time.perf_counter() - start_time) * 1000
+            op_logger.request_failed(method, endpoint, f"Invalid JSON: {e}")
+            raise NPSAPIError(f"Invalid JSON response: {e}") from e

nps_ctl/cli/__init__.py

@@ -0,0 +1,219 @@
+"""Command-line interface for NPS management.
+
+This package provides the `nps-ctl` command for managing NPS servers.
+
+Submodules:
+    parser: Argument parser definition
+    helpers: Shared helper utilities (table formatting, config path)
+    cmd_status: Status command
+    cmd_clients: Client management commands
+    cmd_tunnels: Tunnel management commands
+    cmd_hosts: Host management commands
+    cmd_sync: Sync and export commands
+    cmd_deploy: Install and uninstall commands
+    cmd_npc: NPC deployment commands
+    cmd_utils: Utility commands (auth key generation)
+"""
+
+import sys
+from collections.abc import Callable
+
+from ..logging import configure_logging, flush_output
+from ..ssh_proxy import SSHProxy
+from .helpers import console, get_default_config_path
+from .parser import create_parser
+
+
+def setup_logging(verbose: bool = False, debug: bool = False) -> None:
+    """Configure logging based on verbosity level.
+
+    Log levels:
+        - Default (no flags): NOTICE - shows key phase information
+        - -v/--verbose: INFO - shows all request/response details
+        - --debug: DEBUG - shows everything including internal details
+
+    Args:
+        verbose: Enable INFO level logging.
+        debug: Enable DEBUG level logging (overrides verbose).
+    """
+    if debug:
+        level = "DEBUG"
+    elif verbose:
+        level = "INFO"
+    else:
+        level = "NOTICE"  # Custom level (25) - shows key phases only
+
+    configure_logging(level=level, use_colors=True)
+
+
+def _dispatch_client_list(args) -> int:
+    """Dispatch client list command with special handling.
+
+    If --update or --dry-run is specified, fetches client info from NPS API
+    and updates clients.toml. Otherwise, displays the API client list.
+
+    Args:
+        args: Parsed command line arguments.
+
+    Returns:
+        Exit code.
+    """
+    update = getattr(args, "update", False)
+    dry_run = getattr(args, "dry_run", False)
+
+    if update or dry_run:
+        from ..cluster import NPSCluster
+
+        from .cmd_npc import handle_npc_list
+
+        cluster = NPSCluster(args.config)
+        handle_npc_list(args, cluster)
+        return 0
+    else:
+        from .cmd_clients import cmd_clients
+
+        return cmd_clients(args)
+
+
+def _dispatch_client_push(args) -> int:
+    """Dispatch client push command.
+
+    Args:
+        args: Parsed command line arguments.
+
+    Returns:
+        Exit code.
+    """
+    from ..cluster import NPSCluster
+    from .cmd_npc import handle_client_push
+
+    cluster = NPSCluster(args.config)
+    handle_client_push(args, cluster)
+    return 0
+
+
+def main() -> int:
+    """Main entry point for nps-ctl CLI."""
+    parser = create_parser()
+    args = parser.parse_args()
+
+    # No command specified -> print top-level help
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    # Command specified but no subcommand -> print command group help
+    subcommand = getattr(args, "subcommand", None)
+    if subcommand is None:
+        # Re-parse to get the subparser and print its help
+        parser.parse_args([args.command, "--help"])
+        return 0  # pragma: no cover (--help exits)
+
+    # Setup logging
+    verbose = getattr(args, "verbose", False)
+    debug = getattr(args, "debug", False)
+    setup_logging(verbose=verbose, debug=debug)
+
+    # Check if this command requires config
+    requires_config = getattr(args, "requires_config", True)
+
+    # Find config file if not specified and required
+    if requires_config and args.config is None:
+        try:
+            args.config = get_default_config_path()
+        except FileNotFoundError as e:
+            print(f"Error: {e}", file=sys.stderr)
+            return 1
+
+    # Handle --auto-proxy option
+    auto_proxy = getattr(args, "auto_proxy", None)
+    ssh_proxy: SSHProxy | None = None
+
+    if auto_proxy:
+        # Create and start SSH SOCKS proxy
+        try:
+            console.print(f"[blue]Creating SSH SOCKS proxy via {auto_proxy}...[/blue]")
+            flush_output()
+            ssh_proxy = SSHProxy(ssh_host=auto_proxy)
+            ssh_proxy.start()
+            # Set socks_proxy for the command to use
+            args.socks_proxy = ssh_proxy.address
+            console.print(f"[green]✓ SSH proxy ready on {ssh_proxy.address}[/green]")
+            flush_output()
+        except Exception as e:
+            console.print(f"[red]Failed to create SSH proxy: {e}[/red]")
+            flush_output()
+            return 1
+
+    try:
+        return _dispatch(args)
+    finally:
+        # Clean up SSH proxy if we created one
+        if ssh_proxy:
+            ssh_proxy.stop()
+
+
+def _dispatch(args) -> int:
+    """Dispatch to the appropriate handler based on (command, subcommand).
+
+    Args:
+        args: Parsed command line arguments with command and subcommand set.
+
+    Returns:
+        Exit code.
+    """
+    from .cmd_deploy import cmd_install, cmd_uninstall
+    from .cmd_hosts import cmd_add_host, cmd_hosts
+    from .cmd_npc import (
+        cmd_client_add,
+        cmd_npc_install,
+        cmd_npc_restart,
+        cmd_npc_status,
+        cmd_npc_uninstall,
+    )
+    from .cmd_status import cmd_status
+    from .cmd_sync import cmd_export, cmd_sync
+    from .cmd_tunnels import cmd_add_tunnel, cmd_tunnels
+    from .cmd_utils import cmd_generate_auth_key
+
+    # Command dispatch table: (command, subcommand) -> handler
+    dispatch_table: dict[tuple[str, str], Callable[..., int]] = {
+        # client commands
+        ("client", "list"): _dispatch_client_list,
+        ("client", "add"): cmd_client_add,
+        ("client", "push"): _dispatch_client_push,
+        ("client", "install"): cmd_npc_install,
+        ("client", "uninstall"): cmd_npc_uninstall,
+        ("client", "status"): cmd_npc_status,
+        ("client", "restart"): cmd_npc_restart,
+        # edge commands
+        ("edge", "status"): cmd_status,
+        ("edge", "install"): cmd_install,
+        ("edge", "uninstall"): cmd_uninstall,
+        ("edge", "sync"): cmd_sync,
+        ("edge", "export"): cmd_export,
+        # tunnel commands
+        ("tunnel", "list"): cmd_tunnels,
+        ("tunnel", "add"): cmd_add_tunnel,
+        # host commands
+        ("host", "list"): cmd_hosts,
+        ("host", "add"): cmd_add_host,
+        # util commands
+        ("util", "generate-auth-key"): cmd_generate_auth_key,
+    }
+
+    key = (args.command, args.subcommand)
+    handler = dispatch_table.get(key)
+
+    if handler is None:
+        print(
+            f"Error: Unknown command '{args.command} {args.subcommand}'",
+            file=sys.stderr,
+        )
+        return 1
+
+    return handler(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

nps_ctl/cli/cmd_clients.py

@@ -0,0 +1,78 @@
+"""CLI command: clients - List and manage NPC clients."""
+
+import argparse
+
+from .. import client_mgmt
+from ..cluster import NPSCluster
+from ..exceptions import NPSError
+from ..types import ClientInfo
+from .helpers import console, create_table, print_error
+
+
+def cmd_clients(args: argparse.Namespace) -> int:
+    """List clients on edge nodes."""
+    try:
+        cluster = NPSCluster(args.config)
+    except FileNotFoundError as e:
+        print_error(str(e))
+        return 1
+
+    if args.all:
+        # Show clients from all edges
+        all_clients = cluster.get_all_clients()
+        for edge_name, clients in all_clients.items():
+            edge = cluster.get_edge(edge_name)
+            region = edge.region if edge else ""
+            console.print(f"\n[bold cyan]=== {edge_name} ({region}) ===[/bold cyan]")
+            _print_clients(clients)
+    else:
+        # Show clients from specific edge
+        edge_name = args.edge
+        if not edge_name:
+            # Use first edge as default
+            edge_name = cluster.edge_names[0] if cluster.edge_names else None
+            if not edge_name:
+                print_error("No edges configured")
+                return 1
+
+        nps = cluster.get_client(edge_name)
+        if not nps:
+            print_error(f"Edge '{edge_name}' not found")
+            return 1
+
+        try:
+            clients = client_mgmt.list_clients(nps)
+            _print_clients(clients)
+        except NPSError as e:
+            print_error(str(e))
+            return 1
+
+    return 0
+
+
+def _print_clients(clients: list[ClientInfo]) -> None:
+    """Print client list as table."""
+    table = create_table()
+    table.add_column("ID", style="dim")
+    table.add_column("Remark", style="bold")
+    table.add_column("VKey", style="dim")
+    table.add_column("Status")
+    table.add_column("Conn", justify="right")
+
+    for c in clients:
+        is_connected = c.get("IsConnect", False)
+        status = (
+            "[green]Connected[/green]" if is_connected else "[red]Disconnected[/red]"
+        )
+        vkey = c.get("VerifyKey", "")
+        vkey_display = vkey[:20] + "..." if len(vkey) > 20 else vkey
+
+        table.add_row(
+            str(c.get("Id", "")),
+            c.get("Remark", ""),
+            vkey_display,
+            status,
+            str(c.get("NowConn", 0)),
+        )
+
+    console.print(table)