clashctl 0.1.0__py3-none-any.whl

clashctl/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

clashctl/__main__.py

@@ -0,0 +1,4 @@
+from clashctl.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

clashctl/api/__init__.py

@@ -0,0 +1,20 @@
+from clashctl.api.client import Clash
+from clashctl.api.errors import (
+    AuthError,
+    ClashError,
+    HTTPStatusError,
+    NotFoundError,
+    StreamError,
+)
+from clashctl.api.streams import stream_logs, stream_traffic
+
+__all__ = [
+    "AuthError",
+    "Clash",
+    "ClashError",
+    "HTTPStatusError",
+    "NotFoundError",
+    "StreamError",
+    "stream_logs",
+    "stream_traffic",
+]

clashctl/api/client.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Any, Self
+from urllib.parse import quote
+
+import httpx
+
+from clashctl.api.errors import (
+    AuthError,
+    ClashError,
+    HTTPStatusError,
+    NotFoundError,
+)
+from clashctl.models import (
+    ClashConfig,
+    Connections,
+    Delay,
+    Proxies,
+    Proxy,
+    Rules,
+    Version,
+)
+
+
+class Clash:
+    """Async client for the Clash external-controller REST API.
+
+    Streaming endpoints (`/traffic`, `/logs`) live in `api.streams` so the
+    client itself can keep a single bounded HTTP timeout.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        secret: str | None = None,
+        timeout_ms: int = 5000,
+    ) -> None:
+        if not base_url.endswith("/"):
+            base_url = base_url + "/"
+        headers: dict[str, str] = {}
+        if secret:
+            headers["Authorization"] = f"Bearer {secret}"
+        self._base_url = base_url
+        self._secret = secret
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            headers=headers,
+            timeout=timeout_ms / 1000,
+        )
+        # Separate client without timeout for long-haul streams; lazily created.
+        self._stream_client: httpx.AsyncClient | None = None
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    @property
+    def secret(self) -> str | None:
+        return self._secret
+
+    def stream_client(self) -> httpx.AsyncClient:
+        """Long-lived client without read timeout, for /traffic and /logs."""
+        if self._stream_client is None:
+            headers: dict[str, str] = {}
+            if self._secret:
+                headers["Authorization"] = f"Bearer {self._secret}"
+            self._stream_client = httpx.AsyncClient(
+                base_url=self._base_url,
+                headers=headers,
+                timeout=httpx.Timeout(connect=5.0, read=None, write=5.0, pool=5.0),
+            )
+        return self._stream_client
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+        if self._stream_client is not None:
+            await self._stream_client.aclose()
+
+    async def _request(self, method: str, path: str, **kw: Any) -> httpx.Response:
+        try:
+            resp = await self._client.request(method, path, **kw)
+        except httpx.HTTPError as e:
+            raise ClashError(f"transport error: {e}") from e
+        self._check_status(resp)
+        return resp
+
+    @staticmethod
+    def _check_status(resp: httpx.Response) -> None:
+        sc = resp.status_code
+        if sc < 400:
+            return
+        if sc in (401, 403):
+            raise AuthError(f"authentication failed (HTTP {sc})")
+        if sc == 404:
+            raise NotFoundError(f"not found: {resp.request.url}")
+        raise HTTPStatusError(sc, resp.text[:200])
+
+    # --- one-shot endpoints -------------------------------------------------
+
+    async def version(self) -> Version:
+        r = await self._request("GET", "version")
+        return Version.model_validate_json(r.content)
+
+    async def configs(self) -> ClashConfig:
+        r = await self._request("GET", "configs")
+        return ClashConfig.model_validate_json(r.content)
+
+    async def reload_configs(self, path: str, force: bool = False) -> None:
+        endpoint = "configs?force" if force else "configs"
+        await self._request("PUT", endpoint, json={"path": path})
+
+    async def proxies(self) -> Proxies:
+        r = await self._request("GET", "proxies")
+        # Clash returns `{"proxies": {...}}`; unwrap.
+        data = r.json()
+        inner = data.get("proxies", data)
+        return Proxies.model_validate(inner)
+
+    async def proxy(self, name: str) -> Proxy:
+        r = await self._request("GET", f"proxies/{quote(name, safe='')}")
+        return Proxy.model_validate_json(r.content)
+
+    async def rules(self) -> Rules:
+        r = await self._request("GET", "rules")
+        return Rules.model_validate_json(r.content)
+
+    async def connections(self) -> Connections:
+        r = await self._request("GET", "connections")
+        return Connections.model_validate_json(r.content)
+
+    async def close_connection(self, conn_id: str) -> None:
+        await self._request("DELETE", f"connections/{quote(conn_id, safe='')}")
+
+    async def close_all_connections(self) -> None:
+        await self._request("DELETE", "connections")
+
+    async def select(self, group: str, proxy: str) -> None:
+        """Switch a Selector group's active member."""
+        await self._request(
+            "PUT",
+            f"proxies/{quote(group, safe='')}",
+            json={"name": proxy},
+        )
+
+    async def delay(self, proxy: str, test_url: str, timeout_ms: int) -> Delay:
+        """Probe a single proxy's latency. Raises on connection failure."""
+        r = await self._request(
+            "GET",
+            f"proxies/{quote(proxy, safe='')}/delay",
+            params={"url": test_url, "timeout": timeout_ms},
+        )
+        return Delay.model_validate_json(r.content)

clashctl/api/errors.py

@@ -0,0 +1,24 @@
+class ClashError(Exception):
+    """Base error for the Clash API client."""
+
+
+class AuthError(ClashError):
+    """401/403 from the Clash controller (bad or missing secret)."""
+
+
+class NotFoundError(ClashError):
+    """404 from the Clash controller."""
+
+
+class HTTPStatusError(ClashError):
+    """Non-2xx response that doesn't fit a more specific subclass."""
+
+    def __init__(self, status_code: int, message: str = "") -> None:
+        super().__init__(
+            f"HTTP {status_code}: {message}" if message else f"HTTP {status_code}"
+        )
+        self.status_code = status_code
+
+
+class StreamError(ClashError):
+    """Streaming endpoint disconnected or produced unparseable data."""

clashctl/api/streams.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+
+import httpx
+
+from clashctl.api.client import Clash
+from clashctl.api.errors import StreamError
+from clashctl.models import LogLine, Traffic
+
+log = logging.getLogger(__name__)
+
+
+async def stream_traffic(client: Clash) -> AsyncIterator[Traffic]:
+    """Yield Traffic samples from `/traffic` until the connection drops."""
+    async for line in _stream_lines(client, "traffic"):
+        try:
+            yield Traffic.model_validate_json(line)
+        except ValueError as e:
+            log.debug("skipping bad /traffic line %r: %s", line[:80], e)
+
+
+async def stream_logs(client: Clash) -> AsyncIterator[LogLine]:
+    """Yield LogLine items from `/logs` until the connection drops."""
+    async for line in _stream_lines(client, "logs"):
+        try:
+            yield LogLine.model_validate_json(line)
+        except ValueError as e:
+            log.debug("skipping bad /logs line %r: %s", line[:80], e)
+
+
+async def _stream_lines(client: Clash, path: str) -> AsyncIterator[str]:
+    """Open a streaming GET and yield each non-empty line."""
+    sc = client.stream_client()
+    try:
+        async with sc.stream("GET", path) as resp:
+            if resp.status_code >= 400:
+                raise StreamError(f"{path} returned HTTP {resp.status_code}")
+            async for raw in resp.aiter_lines():
+                line = raw.strip()
+                if line:
+                    yield line
+    except httpx.HTTPError as e:
+        raise StreamError(f"{path} disconnected: {e}") from e

clashctl/cli.py

@@ -0,0 +1,55 @@
+"""`clashctl` entrypoint.
+
+The full CLI surface is intentionally minimal — clashctl is a TUI app.
+Server management lives inside the TUI (Phase 7).
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import sys
+from pathlib import Path
+
+from clashctl import __version__
+from clashctl.config import default_config_path, load_config
+from clashctl.tui import ClashCtlApp
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="clashctl", description="TUI for the Clash proxy API"
+    )
+    p.add_argument(
+        "-c",
+        "--config",
+        type=Path,
+        default=None,
+        help=f"path to config TOML (default: {default_config_path()})",
+    )
+    p.add_argument("--debug", action="store_true", help="enable verbose logging")
+    p.add_argument("--version", action="version", version=f"clashctl {__version__}")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+
+    if args.debug:
+        # Textual swallows stdout/stderr in alt-screen; route to a file.
+        log_path = os.environ.get("CLASHCTL_DEBUG_LOG", "/tmp/clashctl.log")
+        logging.basicConfig(
+            filename=log_path,
+            level=logging.DEBUG,
+            format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        )
+
+    cfg = load_config(args.config)
+    app = ClashCtlApp(cfg)
+    app.run()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

clashctl/config/__init__.py

@@ -0,0 +1,23 @@
+from clashctl.config.schema import (
+    AppConfig,
+    ConnSortConfig,
+    ProxySortConfig,
+    RuleSortConfig,
+    Server,
+    SortsConfig,
+    UiConfig,
+)
+from clashctl.config.store import default_config_path, load_config, save_config
+
+__all__ = [
+    "AppConfig",
+    "ConnSortConfig",
+    "ProxySortConfig",
+    "RuleSortConfig",
+    "Server",
+    "SortsConfig",
+    "UiConfig",
+    "default_config_path",
+    "load_config",
+    "save_config",
+]

clashctl/config/__main__.py

@@ -0,0 +1,29 @@
+"""`python -m clashctl.config show` — print the resolved config.
+
+Useful for debugging path resolution and TOML parse issues during dev.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from clashctl.config import default_config_path, load_config
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    if not args or args[0] != "show":
+        print("usage: python -m clashctl.config show", file=sys.stderr)
+        return 2
+
+    path = default_config_path()
+    print(f"# config path: {path}", file=sys.stderr)
+    print(f"# exists:      {path.exists()}", file=sys.stderr)
+    cfg = load_config(path)
+    print(json.dumps(cfg.model_dump(mode="json", exclude_none=True), indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

clashctl/config/schema.py

@@ -0,0 +1,135 @@
+"""TOML-backed user config.
+
+Lives at `~/.config/clashctl/config.toml` (resolved via platformdirs).
+This is *clashctl's own* config — distinct from Clash's `/configs` payload
+(`models.config.ClashConfig`).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import urlparse
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from clashctl.state.sort import (
+    ConnSort,
+    ConnSortBy,
+    Order,
+    ProxySort,
+    ProxySortBy,
+    RuleSort,
+    RuleSortBy,
+)
+
+
+class _StrictModel(BaseModel):
+    model_config = ConfigDict(extra="ignore", validate_assignment=True)
+
+
+class Server(_StrictModel):
+    """A Clash controller endpoint."""
+
+    name: str
+    url: str
+    secret: str | None = None
+
+    @field_validator("secret", mode="before")
+    @classmethod
+    def _empty_secret_to_none(cls, v: Any) -> Any:
+        if isinstance(v, str) and v == "":
+            return None
+        return v
+
+    @field_validator("url")
+    @classmethod
+    def _validate_url(cls, v: str) -> str:
+        parsed = urlparse(v)
+        if parsed.scheme not in ("http", "https"):
+            raise ValueError(f"url must be http(s): {v!r}")
+        if not parsed.netloc:
+            raise ValueError(f"url missing host: {v!r}")
+        return v
+
+
+# --- per-list sort blocks --------------------------------------------------
+
+
+class _SortBlock(_StrictModel):
+    by: str
+    order: Order = Order.Asc
+
+
+class ProxySortConfig(_SortBlock):
+    by: ProxySortBy = ProxySortBy.Delay  # type: ignore[assignment]
+
+
+class RuleSortConfig(_SortBlock):
+    by: RuleSortBy = RuleSortBy.Payload  # type: ignore[assignment]
+
+
+class ConnSortConfig(_SortBlock):
+    by: ConnSortBy = ConnSortBy.Time  # type: ignore[assignment]
+    order: Order = Order.Desc
+
+
+class SortsConfig(_StrictModel):
+    proxies: ProxySortConfig = Field(default_factory=ProxySortConfig)
+    rules: RuleSortConfig = Field(default_factory=RuleSortConfig)
+    connections: ConnSortConfig = Field(default_factory=ConnSortConfig)
+
+    def to_runtime(self) -> tuple[ProxySort, RuleSort, ConnSort]:
+        return (
+            ProxySort(by=self.proxies.by, order=self.proxies.order),
+            RuleSort(by=self.rules.by, order=self.rules.order),
+            ConnSort(by=self.connections.by, order=self.connections.order),
+        )
+
+
+# --- UI block --------------------------------------------------------------
+
+
+class UiConfig(_StrictModel):
+    test_url: str = "http://www.gstatic.com/generate_204"
+    test_timeout_ms: int = 5000
+    log_buffer: int = 2000
+    traffic_history: int = 500
+    refresh_slow_secs: float = 5.0
+    refresh_fast_secs: float = 1.0
+    sort: SortsConfig = Field(default_factory=SortsConfig)
+
+
+# --- top-level ------------------------------------------------------------
+
+
+class AppConfig(_StrictModel):
+    """Persisted user config."""
+
+    using: str | None = None
+    servers: list[Server] = Field(default_factory=list)
+    ui: UiConfig = Field(default_factory=UiConfig)
+
+    def using_server(self) -> Server | None:
+        if self.using is None:
+            return None
+        for s in self.servers:
+            if s.url == self.using:
+                return s
+        return None
+
+    def use(self, url: str) -> None:
+        if not any(s.url == url for s in self.servers):
+            raise ValueError(f"server not found: {url}")
+        self.using = url
+
+    def add_server(self, server: Server) -> None:
+        if any(s.url == server.url for s in self.servers):
+            raise ValueError(f"server already exists: {server.url}")
+        self.servers.append(server)
+        if self.using is None:
+            self.using = server.url
+
+    def remove_server(self, url: str) -> None:
+        self.servers = [s for s in self.servers if s.url != url]
+        if self.using == url:
+            self.using = self.servers[0].url if self.servers else None

clashctl/config/store.py

@@ -0,0 +1,56 @@
+"""Loading and saving the TOML config file."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+from typing import Any
+
+import tomli_w
+from platformdirs import user_config_dir
+
+from clashctl.config.schema import AppConfig
+
+_APP_NAME = "clashctl"
+_CONFIG_FILENAME = "config.toml"
+
+
+def default_config_path() -> Path:
+    """Return the canonical config path, respecting `CLASHCTL_CONFIG_PATH`.
+
+    Falls back to `<user_config_dir>/clashctl/config.toml` (XDG on Linux,
+    AppData on Windows, ~/Library/Application Support on macOS).
+    """
+    override = os.environ.get("CLASHCTL_CONFIG_PATH")
+    if override:
+        return Path(override).expanduser()
+    return Path(user_config_dir(_APP_NAME)) / _CONFIG_FILENAME
+
+
+def load_config(path: Path | None = None) -> AppConfig:
+    """Read and validate the config file. Returns defaults if missing."""
+    p = path or default_config_path()
+    if not p.exists():
+        return AppConfig()
+    raw = tomllib.loads(p.read_text(encoding="utf-8"))
+    return AppConfig.model_validate(raw)
+
+
+def save_config(config: AppConfig, path: Path | None = None) -> Path:
+    """Atomically write `config` to `path`. Creates parent dirs as needed.
+
+    Returns the path written.
+    """
+    p = path or default_config_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+
+    # `model_dump(mode="json")` coerces enums to their string values, which
+    # is what tomli_w expects. `exclude_none=True` keeps the file tidy.
+    data: dict[str, Any] = config.model_dump(mode="json", exclude_none=True)
+    payload = tomli_w.dumps(data)
+
+    tmp = p.with_suffix(p.suffix + ".tmp")
+    tmp.write_text(payload, encoding="utf-8")
+    os.replace(tmp, p)
+    return p

clashctl/models/__init__.py

@@ -0,0 +1,28 @@
+from clashctl.models.config import ClashConfig
+from clashctl.models.connection import Connection, Connections, Metadata
+from clashctl.models.enums import LogLevel, Mode, ProxyType, RuleType
+from clashctl.models.log import LogLine
+from clashctl.models.proxy import Delay, History, Proxies, Proxy
+from clashctl.models.rule import Rule, Rules
+from clashctl.models.traffic import Traffic
+from clashctl.models.version import Version
+
+__all__ = [
+    "ClashConfig",
+    "Connection",
+    "Connections",
+    "Delay",
+    "History",
+    "LogLevel",
+    "LogLine",
+    "Metadata",
+    "Mode",
+    "Proxies",
+    "Proxy",
+    "ProxyType",
+    "Rule",
+    "RuleType",
+    "Rules",
+    "Traffic",
+    "Version",
+]

clashctl/models/base.py

@@ -0,0 +1,24 @@
+from pydantic import BaseModel, ConfigDict
+from pydantic.alias_generators import to_camel
+
+
+class ClashModel(BaseModel):
+    """Base for Clash API models. Most endpoints use camelCase JSON keys."""
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        alias_generator=to_camel,
+    )
+
+
+def _to_kebab(name: str) -> str:
+    return name.replace("_", "-")
+
+
+class ClashKebabModel(BaseModel):
+    """Base for endpoints using kebab-case (notably `/configs`)."""
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        alias_generator=_to_kebab,
+    )

clashctl/models/config.py

@@ -0,0 +1,37 @@
+from typing import Any
+
+from pydantic import Field, field_validator
+
+from clashctl.models.base import ClashKebabModel
+from clashctl.models.enums import LogLevel, Mode
+
+
+class ClashConfig(ClashKebabModel):
+    """Mirror of Clash's `/configs` payload (kebab-case keys)."""
+
+    port: int = 0
+    socks_port: int = 0
+    redir_port: int = 0
+    tproxy_port: int = 0
+    mixed_port: int = 0
+    allow_lan: bool = False
+    ipv6: bool = False
+    mode: Mode = Mode.Rule
+    log_level: LogLevel = LogLevel.Info
+    bind_address: str = ""
+    authentication: list[str] = Field(default_factory=list)
+
+    @field_validator("mode", mode="before")
+    @classmethod
+    def _coerce_mode(cls, v: Any) -> Any:
+        return Mode(v) if isinstance(v, str) else v
+
+    @field_validator("log_level", mode="before")
+    @classmethod
+    def _coerce_log_level(cls, v: Any) -> Any:
+        return LogLevel(v) if isinstance(v, str) else v
+
+    @field_validator("authentication", mode="before")
+    @classmethod
+    def _coerce_authentication(cls, v: Any) -> Any:
+        return [] if v is None else v