servctl 1.0.0__py3-none-any.whl

servctl/__init__.py

@@ -0,0 +1,4 @@
+"""servctl - Unprivileged Background Server & Localhost Proxy Manager."""
+
+__version__ = "1.0.0"
+__all__ = ["__version__"]

servctl/main.py

@@ -0,0 +1,1123 @@
+#!/usr/bin/env python3
+"""
+servctl.main
+Complete unprivileged server manager and background daemon runner.
+Zero external dependencies (Python Standard Library only).
+"""
+
+import argparse
+import email
+from email import policy
+import http.server
+import ipaddress
+import json
+import os
+from pathlib import Path
+import select
+import signal
+import socket
+import socketserver
+import ssl
+import subprocess
+import sys
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+# Global file system paths
+APP_DIR = Path.home() / ".servctl"
+REGISTRY_FILE = APP_DIR / "registry.json"
+LOGS_DIR = APP_DIR / "logs"
+DNS_CACHE_FILE = APP_DIR / "dns_cache.json"
+CERT_FILE = APP_DIR / "cert.pem"
+KEY_FILE = APP_DIR / "key.pem"
+
+DEFAULT_PORTS = {
+    "web": 8080,
+    "websecure": 8443,
+    "ftps": 2121,
+    "dns": 5353,
+    "proxy": 8888
+}
+
+# ---------------------------------------------------------------------------
+# Utility Functions
+# ---------------------------------------------------------------------------
+
+def ensure_dirs():
+    APP_DIR.mkdir(parents=True, exist_ok=True)
+    LOGS_DIR.mkdir(parents=True, exist_ok=True)
+
+def get_ssl_context() -> ssl.SSLContext:
+    """Ensures self-signed certificates exist and returns an SSLContext."""
+    ensure_dirs()
+    if not (CERT_FILE.exists() and KEY_FILE.exists()):
+        cmd = [
+            "openssl", "req", "-x509", "-newkey", "rsa:2048",
+            "-keyout", str(KEY_FILE), "-out", str(CERT_FILE),
+            "-days", "3650", "-nodes",
+            "-subj", "/CN=localhost"
+        ]
+        try:
+            subprocess.run(cmd, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        except Exception:
+            # Fallback self-signed cert if system openssl command is unavailable
+            fallback_cert = (
+                "-----BEGIN CERTIFICATE-----\n"
+                "MIICpDCCAYwCCQCg/y8U0O9sETANBgkqhkiG9w0BAQsFADAUMRIwEAYDVQQDDAls\n"
+                "b2NhbGhvc3QwIBcNMjMwMTAxMDAwMDAwWhgPMjEyMzAxMDEMDAwMDAwWjAUMRIw\n"
+                "EAYDVQQDDAlsb2NhbGhvc3QwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB\n"
+                "AQDCKqO074bE/X6Ua6Pvx/68xJ3gqUuS7D8FwzTfKk7z2bJp5P+dGZ8sY0fWkP1w\n"
+                "4F9lZ+LpC2zN6L7p0l7g0aJ+ZqM6k7Y1d0r1Jk8r0vO2w3eE2lFpD6mRk+X8c2eP\n"
+                "AgMBAAEwDQYJKoZIhvcNAQELBQADggEBAJ5p5F8j8p1wF8r2t6n4m7u3p6L7k8f1\n"
+                "-----END CERTIFICATE-----\n"
+            )
+            fallback_key = (
+                "-----BEGIN PRIVATE KEY-----\n"
+                "MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDCKqO074bE/X6U\n"
+                "a6Pvx/68xJ3gqUuS7D8FwzTfKk7z2bJp5P+dGZ8sY0fWkP1w4F9lZ+LpC2zN6L7p\n"
+                "-----END PRIVATE KEY-----\n"
+            )
+            CERT_FILE.write_text(fallback_cert)
+            KEY_FILE.write_text(fallback_key)
+
+    ctx = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
+    ctx.load_cert_chain(certfile=str(CERT_FILE), keyfile=str(KEY_FILE))
+    return ctx
+
+def get_local_ip() -> str:
+    """Finds the local network (LAN) IP for other devices on Wi-Fi/Ethernet."""
+    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        s.connect(("10.254.254.254", 1))
+        return s.getsockname()[0]
+    except Exception:
+        return "127.0.0.1"
+    finally:
+        s.close()
+
+def is_port_in_use(port: int, host: str = "127.0.0.1", udp: bool = False) -> bool:
+    sock_type = socket.SOCK_DGRAM if udp else socket.SOCK_STREAM
+    with socket.socket(socket.AF_INET, sock_type) as s:
+        try:
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            s.bind((host, port))
+            return False
+        except OSError:
+            return True
+
+def is_pid_running(pid: int) -> bool:
+    if pid <= 0:
+        return False
+    try:
+        os.kill(pid, 0)
+        return True
+    except (OSError, PermissionError):
+        return False
+
+def read_registry() -> dict:
+    ensure_dirs()
+    if not REGISTRY_FILE.exists():
+        return {}
+    try:
+        with open(REGISTRY_FILE, "r") as f:
+            return json.load(f)
+    except Exception:
+        return {}
+
+def write_registry(data: dict):
+    ensure_dirs()
+    tmp = REGISTRY_FILE.with_suffix(".tmp")
+    with open(tmp, "w") as f:
+        json.dump(data, f, indent=2)
+    tmp.replace(REGISTRY_FILE)
+
+def clean_registry() -> dict:
+    reg = read_registry()
+    updated = {sid: meta for sid, meta in reg.items() if is_pid_running(meta["pid"])}
+    if len(updated) != len(reg):
+        write_registry(updated)
+    return updated
+
+def format_uptime(seconds: float) -> str:
+    s = int(seconds)
+    if s < 60:
+        return f"{s}s"
+    m, s = divmod(s, 60)
+    if m < 60:
+        return f"{m}m {s}s"
+    h, m = divmod(m, 60)
+    if h < 24:
+        return f"{h}h {m}m"
+    d, h = divmod(h, 24)
+    return f"{d}d {h}h"
+
+# ---------------------------------------------------------------------------
+# 1. DNS Resolver Engine (Cloudflare DoH 1.1.1.1)
+# ---------------------------------------------------------------------------
+
+DNS_CACHE = {}
+DNS_LOCK = threading.Lock()
+
+def load_dns_cache_file():
+    global DNS_CACHE
+    if DNS_CACHE_FILE.exists():
+        try:
+            with open(DNS_CACHE_FILE, "r") as f:
+                DNS_CACHE = json.load(f)
+        except Exception:
+            DNS_CACHE = {}
+
+def flush_dns_cache_file():
+    with DNS_LOCK:
+        try:
+            with open(DNS_CACHE_FILE, "w") as f:
+                json.dump(DNS_CACHE, f, indent=2)
+        except Exception:
+            pass
+
+def doh_resolve(hostname: str, ip_target="1.1.1.1", host_hdr="cloudflare-dns.com", path_base="/dns-query"):
+    clean_host = hostname.strip("[]").strip().rstrip(".")
+    now = time.time()
+
+    try:
+        ipaddress.ip_address(clean_host)
+        return clean_host
+    except ValueError:
+        pass
+
+    with DNS_LOCK:
+        if clean_host in DNS_CACHE:
+            rec = DNS_CACHE[clean_host]
+            if isinstance(rec, dict) and rec.get("expires", 0) > now:
+                return rec["ip"]
+
+    if clean_host.endswith((".local", ".test", ".localhost", ".internal")):
+        return "127.0.0.1"
+
+    for _ in range(2):
+        try:
+            ctx = ssl.create_default_context()
+            sock = socket.create_connection((ip_target, 443), timeout=3.0)
+            ssock = ctx.wrap_socket(sock, server_hostname=host_hdr)
+            query_path = f"{path_base}?name={urllib.parse.quote(clean_host)}&type=A"
+            req = (
+                f"GET {query_path} HTTP/1.1\r\n"
+                f"Host: {host_hdr}\r\n"
+                f"Accept: application/dns-json\r\n"
+                f"User-Agent: servctl-DoH/1.0\r\n"
+                f"Connection: close\r\n\r\n"
+            )
+            ssock.sendall(req.encode("utf-8"))
+            raw_resp = b""
+            while True:
+                chunk = ssock.recv(4096)
+                if not chunk:
+                    break
+                raw_resp += chunk
+            ssock.close()
+
+            start = raw_resp.find(b'{')
+            end = raw_resp.rfind(b'}')
+            if start != -1 and end != -1 and end > start:
+                data = json.loads(raw_resp[start:end+1].decode("utf-8", errors="ignore"))
+                for answer in data.get("Answer", []):
+                    if answer.get("type") == 1:
+                        ip = answer.get("data")
+                        ttl = answer.get("TTL", 300)
+                        with DNS_LOCK:
+                            DNS_CACHE[clean_host] = {"ip": ip, "expires": now + ttl}
+                        flush_dns_cache_file()
+                        return ip
+        except Exception:
+            time.sleep(0.05)
+
+    return "127.0.0.1"
+
+def parse_dns_domain(data: bytes) -> str:
+    if len(data) < 13:
+        return ""
+    idx = 12
+    parts = []
+    while idx < len(data):
+        l = data[idx]
+        if l == 0:
+            break
+        idx += 1
+        parts.append(data[idx:idx+l].decode("ascii", errors="ignore"))
+        idx += l
+    return ".".join(parts)
+
+def build_dns_a_response(query: bytes, ip_str: str, ttl: int = 120) -> bytes:
+    tx_id = query[:2]
+    flags = b'\x81\x80'
+    counts = b'\x00\x01\x00\x01\x00\x00\x00\x00'
+    idx = 12
+    while idx < len(query):
+        l = query[idx]
+        if l == 0:
+            idx += 5
+            break
+        idx += 1 + l
+    question = query[12:idx]
+    ttl_bytes = int(ttl).to_bytes(4, byteorder="big")
+    ans = b'\xc0\x0c\x00\x01\x00\x01' + ttl_bytes + b'\x00\x04' + socket.inet_aton(ip_str)
+    return tx_id + flags + counts + question + ans
+
+class DNSUDPHandler(socketserver.BaseRequestHandler):
+    def handle(self):
+        data, sock = self.request
+        domain = parse_dns_domain(data)
+        resolved_ip = doh_resolve(domain)
+        reply = build_dns_a_response(data, resolved_ip)
+        sock.sendto(reply, self.client_address)
+        print(f"[{time.strftime('%X')}] [DNS] Query: {domain} -> {resolved_ip}")
+
+# ---------------------------------------------------------------------------
+# 2. RFC 4217 Explicit FTPS (TLS Encrypted FTP Server)
+# ---------------------------------------------------------------------------
+
+class FTPSClientSession(threading.Thread):
+    def __init__(self, conn, addr, root_dir, ssl_ctx):
+        super().__init__(daemon=True)
+        self.conn = conn
+        self.addr = addr
+        self.root_dir = os.path.realpath(root_dir)
+        self.ssl_ctx = ssl_ctx
+        self.cwd = "/"
+        self.pasv_sock = None
+        self.is_tls = False
+        self.prot = "C"
+
+    def _safe_path(self, path: str):
+        if not path:
+            path = self.cwd
+        elif not path.startswith("/"):
+            path = os.path.join(self.cwd, path)
+        norm = os.path.normpath(path)
+        rel = norm.lstrip("/")
+        full = os.path.realpath(os.path.join(self.root_dir, rel))
+        if full == self.root_dir or full.startswith(self.root_dir + os.sep):
+            return full, norm
+        return None, None
+
+    def send_resp(self, code: int, msg: str):
+        self.conn.sendall(f"{code} {msg}\r\n".encode("utf-8"))
+
+    def _open_data_channel(self):
+        if not self.pasv_sock:
+            self.send_resp(425, "Use PASV or EPSV first.")
+            return None
+        self.send_resp(150, "Opening data connection.")
+        self.pasv_sock.settimeout(10.0)
+        try:
+            raw_conn, _ = self.pasv_sock.accept()
+        except Exception:
+            return None
+        finally:
+            self.pasv_sock.close()
+            self.pasv_sock = None
+
+        if self.prot == "P" and self.is_tls:
+            try:
+                return self.ssl_ctx.wrap_socket(raw_conn, server_side=True)
+            except Exception:
+                raw_conn.close()
+                return None
+        return raw_conn
+
+    def _close_data_channel(self, data_sock):
+        if hasattr(data_sock, "unwrap"):
+            try:
+                data_sock.unwrap()
+            except Exception:
+                pass
+        try:
+            data_sock.close()
+        except Exception:
+            pass
+
+    def run(self):
+        self.send_resp(220, "servctl FTPS Ready (Explicit TLS Required).")
+        f = self.conn.makefile("r", encoding="latin-1", errors="replace")
+        try:
+            while True:
+                line = f.readline()
+                if not line:
+                    break
+                line = line.strip()
+                if not line:
+                    continue
+                parts = line.split(" ", 1)
+                cmd = parts[0].upper()
+                arg = parts[1].strip() if len(parts) > 1 else ""
+
+                if cmd == "AUTH" and arg.upper() in ("TLS", "SSL"):
+                    self.send_resp(234, "AUTH TLS successful. Proceed with TLS handshake.")
+                    try:
+                        self.conn = self.ssl_ctx.wrap_socket(self.conn, server_side=True)
+                        f = self.conn.makefile("r", encoding="latin-1", errors="replace")
+                        self.is_tls = True
+                        self.prot = "P"
+                    except Exception:
+                        break
+
+                elif cmd == "PBSZ":
+                    self.send_resp(200, "PBSZ 0 successful.")
+
+                elif cmd == "PROT":
+                    if arg.upper() in ("P", "C"):
+                        self.prot = arg.upper()
+                        self.send_resp(200, f"Data protection level set to {self.prot}.")
+                    else:
+                        self.send_resp(504, "Unsupported protection level.")
+
+                elif cmd in ("USER", "PASS") and not self.is_tls:
+                    self.send_resp(530, "TLS Required. Please send AUTH TLS first.")
+
+                elif cmd == "USER":
+                    self.send_resp(331, "Any password accepted.")
+
+                elif cmd == "PASS":
+                    self.send_resp(230, "Logged in securely via TLS.")
+
+                elif cmd == "SYST":
+                    self.send_resp(215, "UNIX Type: L8")
+
+                elif cmd == "FEAT":
+                    feat = "211-Features:\r\n AUTH TLS\r\n PBSZ\r\n PROT\r\n PASV\r\n EPSV\r\n UTF8\r\n SIZE\r\n211 End"
+                    self.conn.sendall(feat.encode("utf-8") + b"\r\n")
+
+                elif cmd == "PWD":
+                    self.send_resp(257, f'"{self.cwd}" is current directory.')
+
+                elif cmd == "TYPE":
+                    self.send_resp(200, "Type set.")
+
+                elif cmd == "CWD":
+                    target, norm = self._safe_path(arg)
+                    if target and os.path.isdir(target):
+                        self.cwd = norm
+                        self.send_resp(250, f'Directory changed to "{self.cwd}".')
+                    else:
+                        self.send_resp(550, "Directory not found.")
+
+                elif cmd == "CDUP":
+                    parent = os.path.dirname(self.cwd) or "/"
+                    target, norm = self._safe_path(parent)
+                    if target and os.path.isdir(target):
+                        self.cwd = norm
+                        self.send_resp(200, f'Directory changed to "{self.cwd}".')
+                    else:
+                        self.send_resp(550, "Failed to change directory.")
+
+                elif cmd == "PASV":
+                    if self.pasv_sock:
+                        self.pasv_sock.close()
+                    self.pasv_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+                    self.pasv_sock.bind((self.conn.getsockname()[0], 0))
+                    self.pasv_sock.listen(1)
+                    p_port = self.pasv_sock.getsockname()[1]
+                    p_ip = self.conn.getsockname()[0].replace(".", ",")
+                    self.send_resp(227, f"Entering Passive Mode ({p_ip},{p_port // 256},{p_port % 256}).")
+
+                elif cmd == "EPSV":
+                    if self.pasv_sock:
+                        self.pasv_sock.close()
+                    self.pasv_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+                    self.pasv_sock.bind((self.conn.getsockname()[0], 0))
+                    self.pasv_sock.listen(1)
+                    p_port = self.pasv_sock.getsockname()[1]
+                    self.send_resp(229, f"Entering Extended Passive Mode (|||{p_port}|)")
+
+                elif cmd in ("LIST", "NLST"):
+                    target, _ = self._safe_path(arg)
+                    if not target or not os.path.exists(target):
+                        self.send_resp(550, "Directory not found.")
+                        continue
+                    data_conn = self._open_data_channel()
+                    if not data_conn:
+                        continue
+                    try:
+                        entries = os.listdir(target) if os.path.isdir(target) else [os.path.basename(target)]
+                        lines = []
+                        for e in entries:
+                            if cmd == "NLST":
+                                lines.append(f"{e}\r\n")
+                            else:
+                                full = os.path.join(target, e) if os.path.isdir(target) else target
+                                is_d = os.path.isdir(full)
+                                perms = "drwxr-xr-x" if is_d else "-rw-r--r--"
+                                size = os.path.getsize(full) if not is_d else 4096
+                                lines.append(f"{perms} 1 owner group {size:8d} Jan 01 00:00 {e}\r\n")
+                        data_conn.sendall("".join(lines).encode("utf-8"))
+                    finally:
+                        self._close_data_channel(data_conn)
+                    self.send_resp(226, "Directory listing complete.")
+
+                elif cmd == "RETR":
+                    target, _ = self._safe_path(arg)
+                    if not target or not os.path.isfile(target):
+                        self.send_resp(550, "File not found.")
+                        continue
+                    data_conn = self._open_data_channel()
+                    if not data_conn:
+                        continue
+                    try:
+                        with open(target, "rb") as df:
+                            while chunk := df.read(16384):
+                                data_conn.sendall(chunk)
+                    finally:
+                        self._close_data_channel(data_conn)
+                    self.send_resp(226, "Transfer complete.")
+
+                elif cmd == "STOR":
+                    target, _ = self._safe_path(arg)
+                    if not target:
+                        self.send_resp(553, "Invalid path.")
+                        continue
+                    data_conn = self._open_data_channel()
+                    if not data_conn:
+                        continue
+                    try:
+                        with open(target, "wb") as df:
+                            while chunk := data_conn.recv(16384):
+                                df.write(chunk)
+                    finally:
+                        self._close_data_channel(data_conn)
+                    self.send_resp(226, "Upload successful.")
+
+                elif cmd == "SIZE":
+                    target, _ = self._safe_path(arg)
+                    if target and os.path.isfile(target):
+                        self.send_resp(213, str(os.path.getsize(target)))
+                    else:
+                        self.send_resp(550, "File not found.")
+
+                elif cmd == "DELE":
+                    target, _ = self._safe_path(arg)
+                    if target and os.path.isfile(target):
+                        try:
+                            os.remove(target)
+                            self.send_resp(250, "File deleted.")
+                        except Exception as e:
+                            self.send_resp(550, f"Delete failed: {e}")
+                    else:
+                        self.send_resp(550, "File not found.")
+
+                elif cmd == "MKD":
+                    target, norm = self._safe_path(arg)
+                    if target:
+                        try:
+                            os.makedirs(target, exist_ok=True)
+                            self.send_resp(257, f'"{norm}" directory created.')
+                        except Exception as e:
+                            self.send_resp(550, f"Create failed: {e}")
+                    else:
+                        self.send_resp(550, "Invalid path.")
+
+                elif cmd == "QUIT":
+                    self.send_resp(221, "Goodbye.")
+                    break
+
+                elif cmd == "NOOP":
+                    self.send_resp(200, "OK.")
+
+                else:
+                    self.send_resp(502, f"Command '{cmd}' not implemented.")
+        finally:
+            try:
+                self.conn.close()
+            except Exception:
+                pass
+            if self.pasv_sock:
+                self.pasv_sock.close()
+
+def start_ftps_server(host, port, root_dir):
+    ssl_ctx = get_ssl_context()
+    srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    srv.bind((host, port))
+    srv.listen(10)
+    print(f"[{time.strftime('%X')}] FTPS server (TLS) listening on {host}:{port} (Root: {root_dir})")
+    while True:
+        try:
+            conn, addr = srv.accept()
+            FTPSClientSession(conn, addr, root_dir, ssl_ctx).start()
+        except Exception:
+            break
+
+# ---------------------------------------------------------------------------
+# 3. Web & Proxy Server Handlers
+# ---------------------------------------------------------------------------
+
+class DefaultWebHandler(http.server.SimpleHTTPRequestHandler):
+    def __init__(self, *args, directory=None, **kwargs):
+        super().__init__(*args, directory=directory, **kwargs)
+
+    def end_headers(self):
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.send_header("Access-Control-Allow-Methods", "GET, POST, OPTIONS, PUT, DELETE")
+        self.send_header("Access-Control-Allow-Headers", "*")
+        self.send_header("Cache-Control", "no-cache, no-store, must-revalidate")
+        super().end_headers()
+
+    def do_GET(self):
+        path = self.translate_path(self.path)
+        if not os.path.exists(path) and not self.path.startswith("/api"):
+            index_path = os.path.join(self.directory, "index.html")
+            if os.path.exists(index_path):
+                self.path = "/index.html"
+        return super().do_GET()
+
+class ProxyHandler(http.server.SimpleHTTPRequestHandler):
+    def do_CONNECT(self):
+        try:
+            host, port = self.path.split(":")
+            remote = socket.create_connection((host, int(port)), timeout=10)
+            self.send_response(200, "Connection Established")
+            self.end_headers()
+
+            sockets = [self.connection, remote]
+            while True:
+                r, _, _ = select.select(sockets, [], sockets, 60)
+                if not r:
+                    break
+                for s in r:
+                    other = remote if s is self.connection else self.connection
+                    data = s.recv(8192)
+                    if not data:
+                        return
+                    other.sendall(data)
+        except Exception as e:
+            self.send_error(502, f"Tunnel Error: {e}")
+
+    def do_proxy(self):
+        target_base = getattr(self.server, "target", None)
+        url = urllib.parse.urljoin(target_base, self.path) if target_base else self.path
+        length = int(self.headers.get("Content-Length", 0))
+        body = self.rfile.read(length) if length > 0 else None
+
+        req_headers = dict(self.headers)
+        for h in ["Connection", "Keep-Alive", "Proxy-Authenticate", "TE", "Transfer-Encoding", "Upgrade"]:
+            req_headers.pop(h, None)
+            req_headers.pop(h.lower(), None)
+
+        if target_base:
+            req_headers["Host"] = urllib.parse.urlsplit(target_base).netloc
+            req_headers["X-Forwarded-For"] = self.client_address[0]
+
+        req = urllib.request.Request(url, data=body, headers=req_headers, method=self.command)
+        try:
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                self.send_response(resp.status)
+                for k, v in resp.getheaders():
+                    if k.lower() not in ["transfer-encoding", "content-length"]:
+                        self.send_header(k, v)
+                data = resp.read()
+                self.send_header("Content-Length", str(len(data)))
+                self.end_headers()
+                self.wfile.write(data)
+        except urllib.error.HTTPError as e:
+            self.send_response(e.code)
+            data = e.read()
+            self.send_header("Content-Length", str(len(data)))
+            self.end_headers()
+            self.wfile.write(data)
+        except Exception as e:
+            self.send_error(502, f"Bad Gateway: {e}")
+
+    do_GET = do_proxy
+    do_POST = do_proxy
+    do_PUT = do_proxy
+    do_DELETE = do_proxy
+    do_PATCH = do_proxy
+
+# ---------------------------------------------------------------------------
+# Background Daemon Worker Entrypoint
+# ---------------------------------------------------------------------------
+
+def run_worker(args):
+    sys.stdout.reconfigure(line_buffering=True)
+    sys.stderr.reconfigure(line_buffering=True)
+
+    signal.signal(signal.SIGTERM, lambda *_: sys.exit(0))
+    signal.signal(signal.SIGINT, lambda *_: sys.exit(0))
+
+    host = args.host
+    port = args.port
+    srv_type = args.type
+    root = Path(args.root).expanduser().resolve()
+
+    if root.is_dir():
+        os.chdir(root)
+
+    if srv_type in ("ftp", "ftps", "fileshare"):
+        start_ftps_server(host, port, str(root))
+
+    elif srv_type in ("websecure", "https"):
+        class ThreadedHTTPServer(http.server.ThreadingHTTPServer):
+            allow_reuse_address = True
+        handler = lambda *hargs, **hkwargs: DefaultWebHandler(*hargs, directory=str(root), **hkwargs)
+        server = ThreadedHTTPServer((host, port), handler)
+        ssl_ctx = get_ssl_context()
+        server.socket = ssl_ctx.wrap_socket(server.socket, server_side=True)
+        print(f"[{time.strftime('%X')}] Secure HTTPS Web Server running on {host}:{port} (Root: {root})")
+        server.serve_forever()
+
+    elif srv_type in ("web", "website"):
+        class ThreadedHTTPServer(http.server.ThreadingHTTPServer):
+            allow_reuse_address = True
+        handler = lambda *hargs, **hkwargs: DefaultWebHandler(*hargs, directory=str(root), **hkwargs)
+        server = ThreadedHTTPServer((host, port), handler)
+        print(f"[{time.strftime('%X')}] Default HTTP Web Server running on {host}:{port} (Root: {root})")
+        server.serve_forever()
+
+    elif srv_type == "dns":
+        load_dns_cache_file()
+        class ThreadedUDPServer(socketserver.ThreadingMixIn, socketserver.UDPServer):
+            allow_reuse_address = True
+        server = ThreadedUDPServer((host, port), DNSUDPHandler)
+        print(f"[{time.strftime('%X')}] DNS DoH Resolver (1.1.1.1) running on {host}:{port}")
+        server.serve_forever()
+
+    elif srv_type == "proxy":
+        class ThreadedHTTPServer(http.server.ThreadingHTTPServer):
+            allow_reuse_address = True
+        server = ThreadedHTTPServer((host, port), ProxyHandler)
+        server.target = args.target
+        print(f"[{time.strftime('%X')}] Proxy server running on {host}:{port}")
+        server.serve_forever()
+
+# ---------------------------------------------------------------------------
+# CLI Commands
+# ---------------------------------------------------------------------------
+
+def cmd_start(args):
+    clean_registry()
+
+    # Canonical type mapping
+    if args.type in ("websecure", "https"):
+        canonical_type = "websecure"
+    elif args.type in ("ftp", "ftps", "fileshare"):
+        canonical_type = "ftps"
+    elif args.type in ("web", "website"):
+        canonical_type = "web"
+    else:
+        canonical_type = args.type
+
+    port = args.port or DEFAULT_PORTS.get(canonical_type, 8080)
+    host = "0.0.0.0" if args.access == "network" else "127.0.0.1"
+    is_udp = (canonical_type == "dns")
+
+    if port < 1024 and os.name != "nt" and os.geteuid() != 0:
+        print(f"Error: Port {port} is a privileged port (< 1024) requiring root/sudo.")
+        print(f"To run servctl without sudo, use an unprivileged port (default is {DEFAULT_PORTS.get(canonical_type)}).")
+        sys.exit(1)
+
+    raw_root = args.root or args.path or "."
+    root_path = Path(raw_root).expanduser().resolve()
+
+    if canonical_type in ("web", "websecure", "ftps") and not root_path.is_dir():
+        print(f"Error: Directory '{root_path}' does not exist.")
+        sys.exit(1)
+
+    if is_port_in_use(port, host, udp=is_udp):
+        print(f"Error: Port {port} ({'UDP' if is_udp else 'TCP'}) is already in use on {host}.")
+        sys.exit(1)
+
+    srv_id = args.name or f"{canonical_type}-{port}"
+    ensure_dirs()
+    log_path = LOGS_DIR / f"{srv_id}.log"
+    log_fd = open(log_path, "a")
+
+    main_file = str(Path(__file__).resolve())
+    pkg_root = str(Path(__file__).resolve().parent.parent)
+    env = os.environ.copy()
+    env["PYTHONPATH"] = os.pathsep.join(filter(None, [pkg_root, env.get("PYTHONPATH", "")]))
+
+    cmd = [
+        sys.executable,
+        main_file,
+        "_worker",
+        "--id", srv_id,
+        "--type", canonical_type,
+        "--port", str(port),
+        "--host", host,
+        "--root", str(root_path),
+    ]
+    if args.target:
+        cmd.extend(["--target", args.target])
+
+    kwargs = {
+        "stdout": log_fd,
+        "stderr": log_fd,
+        "stdin": subprocess.DEVNULL,
+        "cwd": str(root_path),
+        "env": env
+    }
+    if os.name == "nt":
+        kwargs["creationflags"] = subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP
+    else:
+        kwargs["start_new_session"] = True
+
+    proc = subprocess.Popen(cmd, **kwargs)
+    time.sleep(0.4)
+
+    if proc.poll() is not None:
+        log_fd.close()
+        print(f"Error: Server failed to start. Log contents ({log_path}):")
+        with open(log_path) as f:
+            print(f.read())
+        sys.exit(1)
+
+    reg = read_registry()
+    reg[srv_id] = {
+        "id": srv_id,
+        "type": canonical_type,
+        "port": port,
+        "host": host,
+        "access": args.access,
+        "root": str(root_path),
+        "target": args.target,
+        "pid": proc.pid,
+        "started_at": time.time(),
+        "log_file": str(log_path)
+    }
+    write_registry(reg)
+
+    lan_ip = get_local_ip()
+    if canonical_type == "websecure":
+        protocol = "https"
+    elif canonical_type == "ftps":
+        protocol = "ftps"
+    elif canonical_type == "dns":
+        protocol = "dns"
+    else:
+        protocol = "http"
+
+    local_url = f"{protocol}://127.0.0.1:{port}"
+    lan_url = f"{protocol}://{lan_ip}:{port}"
+
+    type_label = "SECURE HTTPS WEB" if canonical_type == "websecure" else canonical_type.upper()
+    print(f"\n✔ Successfully started {type_label} server in background!")
+    print("─" * 66)
+    print(f"  Server ID:      {srv_id}")
+    print(f"  PID:            {proc.pid}")
+    print(f"  Type:           {canonical_type}")
+    print(f"  Port:           {port} ({'UDP' if is_udp else 'TCP'})")
+    print(f"  Access Scope:   {args.access} ({'This device only' if args.access == 'local' else 'LAN Sharing Enabled'})")
+    print(f"  This Device:    {local_url}")
+    if args.access == "network":
+        print(f"  Other Devices:  {lan_url}  <-- Open this on phone, tablet, etc.")
+    else:
+        print(f"  Other Devices:  [Localhost Only] Re-run with '-a network' to access via {lan_url}")
+    print(f"  LAN IP Address: {lan_ip}")
+    if canonical_type in ("web", "websecure", "ftps"):
+        print(f"  Root Dir:       {root_path}")
+    if args.target:
+        print(f"  Target:         {args.target}")
+    print(f"  Log File:       {log_path}")
+    print("─" * 66)
+    if canonical_type == "ftps":
+        connect_host = lan_ip if args.access == "network" else "127.0.0.1"
+        print("  Client Connection:")
+        print(f"    curl --ssl -k ftp://{connect_host}:{port}/")
+        print("    FileZilla / Cyberduck: Require explicit FTP over TLS")
+    elif canonical_type == "websecure":
+        print("  HTTPS Self-Signed Certificate:")
+        print("    Accept the certificate warning in your browser upon first visit.")
+        print(f"    curl -k {local_url}")
+    print(f"  Logs: servctl logs {srv_id}")
+    print(f"  Stop: servctl stop {srv_id}\n")
+
+def cmd_stop(args):
+    reg = read_registry()
+    if not reg:
+        print("No managed servers found.")
+        return
+
+    to_stop_ids = []
+
+    if args.all:
+        to_stop_ids = list(reg.keys())
+    elif args.targets:
+        for query in args.targets:
+            matched = False
+            for sid, meta in reg.items():
+                if sid == query or str(meta["port"]) == query:
+                    if sid not in to_stop_ids:
+                        to_stop_ids.append(sid)
+                    matched = True
+            if not matched:
+                print(f"Warning: No running server matching '{query}'.")
+    else:
+        print("Please specify one or more server IDs/ports, or use --all to stop all.")
+        return
+
+    if not to_stop_ids:
+        return
+
+    for sid in to_stop_ids:
+        meta = reg.pop(sid, None)
+        if not meta:
+            continue
+        pid = meta["pid"]
+        if is_pid_running(pid):
+            try:
+                os.kill(pid, signal.SIGTERM)
+                for _ in range(15):
+                    if not is_pid_running(pid):
+                        break
+                    time.sleep(0.1)
+                if is_pid_running(pid):
+                    os.kill(pid, signal.SIGKILL)
+            except OSError:
+                pass
+            print(f"✔ Stopped server '{sid}' (PID: {pid}).")
+        else:
+            print(f"Server '{sid}' was already inactive.")
+
+    write_registry(reg)
+
+def cmd_list(args):
+    reg = clean_registry()
+    if not reg:
+        print("No servers running. Start one using: servctl start")
+        return
+
+    lan_ip = get_local_ip()
+    headers = ["ID", "TYPE", "PORT", "THIS DEVICE", "OTHER DEVICES (LAN IP)", "ROOT / TARGET", "PID", "UPTIME"]
+    rows = []
+    for sid, m in reg.items():
+        uptime = format_uptime(time.time() - m["started_at"])
+        if m["type"] in ("websecure", "https"):
+            protocol = "https"
+        elif m["type"] in ("ftp", "ftps"):
+            protocol = "ftps"
+        elif m["type"] == "dns":
+            protocol = "dns"
+        else:
+            protocol = "http"
+
+        local_url = f"{protocol}://127.0.0.1:{m['port']}"
+        if m.get("access") == "network":
+            other_dev = f"{protocol}://{lan_ip}:{m['port']}"
+        else:
+            other_dev = f"Local only (LAN: {lan_ip})"
+
+        dest = m.get("target") or m.get("root") or "-"
+        if len(dest) > 22:
+            dest = "..." + dest[-19:]
+        rows.append([sid, m["type"], str(m["port"]), local_url, other_dev, dest, str(m["pid"]), uptime])
+
+    widths = [len(h) for h in headers]
+    for row in rows:
+        for i, val in enumerate(row):
+            widths[i] = max(widths[i], len(val))
+
+    sep = "+-" + "-+-".join("-" * w for w in widths) + "-+"
+    hdr = "| " + " | ".join(h.ljust(widths[i]) for i, h in enumerate(headers)) + " |"
+
+    print("\nActive servctl Servers:")
+    print(sep)
+    print(hdr)
+    print(sep)
+    for row in rows:
+        print("| " + " | ".join(row[i].ljust(widths[i]) for i in range(len(headers))) + " |")
+    print(sep + "\n")
+
+def cmd_logs(args):
+    reg = read_registry()
+    target_meta = next((m for sid, m in reg.items() if sid == args.target or str(m["port"]) == args.target), None)
+    log_path = Path(target_meta["log_file"]) if target_meta else (LOGS_DIR / f"{args.target}.log")
+
+    if not log_path.exists():
+        print(f"Log file '{log_path}' not found.")
+        return
+
+    with open(log_path, "r", errors="replace") as f:
+        lines = f.readlines()
+        for line in lines[-args.lines:]:
+            sys.stdout.write(line)
+        sys.stdout.flush()
+
+        if args.follow:
+            try:
+                while True:
+                    line = f.readline()
+                    if line:
+                        sys.stdout.write(line)
+                        sys.stdout.flush()
+                    else:
+                        time.sleep(0.2)
+            except KeyboardInterrupt:
+                pass
+
+def cmd_man(args):
+    print("""
+================================================================================
+SERVCTL(1)                    User Commands                   SERVCTL(1)
+================================================================================
+
+NAME
+       servctl - Unprivileged background server and localhost proxy manager
+
+SYNOPSIS
+       servctl start [DIRECTORY] [-t TYPE] [-p PORT] [-r ROOT] [-a ACCESS] [--target TARGET] [-n NAME]
+       servctl stop [PORT | ID ...] [--all]
+       servctl list
+       servctl logs [PORT | ID] [-f] [-n LINES]
+       servctl man
+
+DESCRIPTION
+       servctl is a command-line tool that spins up background development
+       servers without requiring root/sudo privileges. Processes run in
+       detached mode, keeping your terminal responsive and free.
+
+ROOT DIRECTORY HANDLING
+       By default, servctl uses the current working directory where you
+       execute the command as the server root.
+
+       You can point to any other custom directory without having to 'cd'
+       into it, either by passing it as a positional argument:
+              $ servctl start ~/Downloads
+
+       Or explicitly using the --root / -r flag:
+              $ servctl start --root /var/www/html
+
+CONNECTING FROM OTHER DEVICES (LAN SHARING)
+       Use the '-a network' flag to allow other computers, phones, or tablets
+       on the same Wi-Fi network to connect.
+
+       servctl automatically detects your device's LAN IP address and prints
+       the exact URL to use on other devices both during startup and in the
+       'servctl list' table.
+
+SERVER TYPES (-t, --type)
+       web (Default)
+              A static HTTP web server with Single Page App (SPA) fallback,
+              permissive CORS, and no-cache development headers.
+              Default port: 8080.
+
+       websecure (or https)
+              A secure HTTPS web server using TLS encryption and auto-generated
+              certificates. Includes SPA fallback, CORS, and no-cache headers.
+              Default port: 8443.
+
+       ftps (or ftp, fileshare)
+              An RFC 4217 Explicit FTPS server. Requires TLS encryption
+              (AUTH TLS) before authenticating. Protects control and data
+              channels (PROT P) with auto-generated certificates.
+              Rejects insecure plaintext requests. Default port: 2121.
+
+       dns
+              A local UDP DNS proxy engine that resolves queries through
+              Cloudflare DNS-over-HTTPS (1.1.1.1:443) with in-memory and
+              disk-backed caching (~/.servctl/dns_cache.json). Resolves .local,
+              .test, and .internal queries to 127.0.0.1. Default port: 5353.
+
+       proxy
+              An HTTP forward proxy (with HTTPS CONNECT tunneling) or reverse
+              proxy when used with --target. Default port: 8888.
+
+ACCESS MODES (-a, --access)
+       local (Default)
+              Binds to 127.0.0.1 (accessible only on this machine).
+
+       network
+              Binds to 0.0.0.0 (accessible to other devices on the LAN/Wi-Fi).
+
+STOPPING SERVERS
+       Stop one server:
+              $ servctl stop 8080
+
+       Stop multiple servers simultaneously:
+              $ servctl stop 8080 8443 2121
+              $ servctl stop web-8080 websecure-8443
+
+       Stop all running servers:
+              $ servctl stop --all
+
+EXAMPLES
+       1. Start a default HTTP website:
+              $ servctl start
+
+       2. Start a secure HTTPS website on port 8443:
+              $ servctl start -t websecure
+
+       3. Start an HTTPS website pointing to another folder for LAN access:
+              $ servctl start -t websecure ~/Projects/site/dist -a network
+
+       4. Start an FTPS server in a custom folder:
+              $ servctl start -t ftps ~/SharedFolder -a network
+
+       5. View running servers and connection URLs:
+              $ servctl list
+
+       6. Stop multiple servers at once:
+              $ servctl stop 8080 8443
+================================================================================
+""")
+
+def main():
+    parser = argparse.ArgumentParser(prog="servctl", description="Unprivileged background server and proxy manager")
+    subparsers = parser.add_subparsers(dest="command")
+
+    # START
+    p_start = subparsers.add_parser("start", help="Start a background server")
+    p_start.add_argument("path", nargs="?", default=None, help="Root directory (default: current working directory)")
+    p_start.add_argument("-r", "--root", default=None, help="Custom root directory path (overrides current directory)")
+    p_start.add_argument("-t", "--type", choices=["web", "website", "websecure", "https", "ftp", "ftps", "fileshare", "dns", "proxy"], default="web", help="Server type (default: web)")
+    p_start.add_argument("-p", "--port", type=int, default=None, help="Port to bind (defaults: web: 8080, websecure: 8443, ftps: 2121, dns: 5353, proxy: 8888)")
+    p_start.add_argument("-a", "--access", choices=["local", "network"], default="local", help="Access scope: local (127.0.0.1) or network (0.0.0.0)")
+    p_start.add_argument("--target", default=None, help="Target URL for reverse proxy")
+    p_start.add_argument("-n", "--name", default=None, help="Custom identifier for this instance")
+
+    # STOP (Accepts multiple targets or --all)
+    p_stop = subparsers.add_parser("stop", help="Stop running servers")
+    p_stop.add_argument("targets", nargs="*", help="One or more Server IDs or Ports to stop")
+    p_stop.add_argument("-a", "--all", action="store_true", help="Stop all running servers")
+
+    # LIST
+    subparsers.add_parser("list", aliases=["ls", "status"], help="List active servers")
+
+    # LOGS
+    p_logs = subparsers.add_parser("logs", help="View server logs")
+    p_logs.add_argument("target", help="Server ID or Port")
+    p_logs.add_argument("-n", "--lines", type=int, default=50, help="Number of lines to show")
+    p_logs.add_argument("-f", "--follow", action="store_true", help="Follow log stream")
+
+    # MAN
+    subparsers.add_parser("man", help="View manual page")
+
+    # HIDDEN WORKER (Invoked by background daemon subprocesses)
+    p_worker = subparsers.add_parser("_worker")
+    p_worker.add_argument("--id", required=True)
+    p_worker.add_argument("--type", required=True)
+    p_worker.add_argument("--port", type=int, required=True)
+    p_worker.add_argument("--host", required=True)
+    p_worker.add_argument("--root", required=True)
+    p_worker.add_argument("--target", default=None)
+
+    args = parser.parse_args()
+
+    if args.command == "_worker":
+        run_worker(args)
+    elif args.command == "start":
+        cmd_start(args)
+    elif args.command == "stop":
+        cmd_stop(args)
+    elif args.command in ("list", "ls", "status"):
+        cmd_list(args)
+    elif args.command == "logs":
+        cmd_logs(args)
+    elif args.command == "man":
+        cmd_man(args)
+    else:
+        parser.print_help()
+
+if __name__ == "__main__":
+    main()

servctl-1.0.0.dist-info/METADATA

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: servctl
+Version: 1.0.0
+Summary: Unprivileged background server and localhost proxy CLI manager
+Author: avevall
+Keywords: cli,devops,dns,doh,ftp,localhost,proxy,server
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: File Transfer Protocol (FTP)
+Classifier: Topic :: Internet :: Name Service (DNS)
+Classifier: Topic :: Internet :: Proxy Servers
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+Hello

servctl-1.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+servctl/__init__.py,sha256=0AJluu-rtCOLCqI2QHldDpx2C1J8sbgHVHY9QVvVtwk,122
+servctl/main.py,sha256=qUXiVBx2wRZmqpza84eErBf9fhp4xNeCg1h9P0SCjGE,42411
+servctl-1.0.0.dist-info/METADATA,sha256=GRU_ru73mM64MhBrG9rhEEjxJX3eKfQSqJPytWp8O08,1119
+servctl-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+servctl-1.0.0.dist-info/entry_points.txt,sha256=NlFnFf_ddskRQDxE6tZWk9Y_ohuctzt90xv5qXEh-fw,46
+servctl-1.0.0.dist-info/RECORD,,

servctl-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

servctl-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+servctl = servctl.main:main