proxyctl 0.5.8__tar.gz → 0.5.9__tar.gz

{proxyctl-0.5.8 → proxyctl-0.5.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyctl
-Version: 0.5.8
+Version: 0.5.9
 Summary: Proxy configuration lifecycle management for macOS and Linux
 Project-URL: Homepage, https://github.com/crhan/proxyctl
 Project-URL: Issues, https://github.com/crhan/proxyctl/issues

{proxyctl-0.5.8 → proxyctl-0.5.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "proxyctl"
-version = "0.5.8"
+version = "0.5.9"
 description = "Proxy configuration lifecycle management for macOS and Linux"
 readme = "README.md"
 requires-python = ">=3.10"

{proxyctl-0.5.8 → proxyctl-0.5.9}/src/proxyctl/builtin_plugins/connectivity_basic.py

@@ -3,7 +3,7 @@
 提供一组跨所有用户都通用的连通性测试点：
 - 海外（走代理）：google / github
 - 国内（直连）：baidu
-- AI 线路：anthropic（走 claude 规则组）
+- AI 线路：openai / anthropic（anthropic 走 claude 规则组）
 
 本机特例（discord/telegram、企业内网等）请走用户插件。
 
@@ -24,9 +24,12 @@ class ConnectivityBasic(Plugin):
         return [
             CheckTarget(name="google", url="https://www.google.com", mode="proxy"),
             CheckTarget(name="github", url="https://github.com",     mode="proxy"),
+            CheckTarget(name="openai",
+                        url="https://api.openai.com/v1/models",
+                        mode="proxy"),
             CheckTarget(name="baidu",  url="https://www.baidu.com",  mode="direct"),
             CheckTarget(name="anthropic",
-                        url="https://api.anthropic.com",
+                        url="https://api.anthropic.com/v1/models",
                         mode="proxy",
                         expected_proxy="claude"),
         ]

{proxyctl-0.5.8 → proxyctl-0.5.9}/src/proxyctl/check.py

@@ -54,7 +54,7 @@ def _test_url(url: str, desc: str, mode: str = "proxy", timeout: int = 8,
     env = {k: v for k, v in os.environ.items()
            if k not in ("http_proxy", "https_proxy", "all_proxy",
                         "HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY")}
-    cmd = ["curl", "-s", "-o", "/dev/null", "-w", "%{http_code}",
+    cmd = ["curl", "--http1.1", "-s", "-o", "/dev/null", "-w", "%{http_code}",
            "--max-time", str(timeout)]
     if mode == "proxy":
         cmd += ["--proxy", f"socks5h://127.0.0.1:{proxy_port}"]
@@ -66,7 +66,8 @@ def _test_url(url: str, desc: str, mode: str = "proxy", timeout: int = 8,
     code = r.stdout.strip()
 
     if code == "000" or not code:
-        return False, f"  {RED}✗{NC} {desc:<18s} {url:<44s} {RED}timeout{NC}"
+        reason = _curl_failure_reason(r.stderr)
+        return False, f"  {RED}✗{NC} {desc:<18s} {url:<44s} {RED}{reason}{NC}"
     elif code.startswith(("2", "3", "4")):
         return True,  f"  {GREEN}✓{NC} {desc:<18s} {url:<44s} {GREEN}{code}{NC}"
     elif code.startswith("5"):
@@ -76,6 +77,16 @@ def _test_url(url: str, desc: str, mode: str = "proxy", timeout: int = 8,
         return False, f"  {YELLOW}?{NC} {desc:<18s} {url:<44s} {YELLOW}{code}{NC}"
 
 
+def _curl_failure_reason(stderr: str) -> str:
+    """Return a concise curl failure reason for HTTP code 000."""
+    text = (stderr or "").strip()
+    if not text:
+        return "timeout"
+    first = text.splitlines()[0].strip()
+    first = first.removeprefix("curl: ").strip()
+    return first[:120] if first else "timeout"
+
+
 def _api_connections(api_base: str, api_secret: str) -> list[dict]:
     r = subprocess.run(
         ["curl", "-s", "--noproxy", "*",
@@ -91,26 +102,119 @@ def _api_connections(api_base: str, api_secret: str) -> list[dict]:
     return conns if isinstance(conns, list) else []
 
 
-def _target_uses_expected_proxy(api_base: str, api_secret: str, url: str,
-                                expected_proxy: str) -> tuple[bool, str]:
+def _route_from_connections(conns: list[dict], host: str) -> dict:
+    """Find one Mihomo route for host and expose leaf line + policy group.
+
+    Mihomo reports chains from leaf node to policy group, for example
+    ``["TW-Residential-01", "residential-tw", "claude"]``. The human
+    "line" is the leaf node, not the policy group.
+    """
+    for conn in conns:
+        meta = conn.get("metadata") or {}
+        conn_host = meta.get("host") or ""
+        if conn_host != host and not conn_host.endswith("." + host):
+            continue
+        chains = [str(c) for c in (conn.get("chains") or []) if c]
+        return {
+            "found": True,
+            "line": chains[0] if chains else "?",
+            "group": chains[-1] if chains else "",
+            "chain": " → ".join(reversed(chains)) if chains else "?",
+        }
+    return {"found": False, "line": "?", "group": "", "chain": ""}
+
+
+def _target_route(api_base: str, api_secret: str, url: str) -> dict:
+    """Return the observed route for a URL from local Mihomo connections."""
     host = urllib.parse.urlparse(url).hostname or ""
-    if not host or not expected_proxy:
-        return True, ""
+    if not host:
+        return {"found": False, "line": "?", "group": "", "chain": ""}
 
     for _ in range(3):
-        for conn in _api_connections(api_base, api_secret):
-            meta = conn.get("metadata") or {}
-            conn_host = meta.get("host") or ""
-            if conn_host != host and not conn_host.endswith("." + host):
-                continue
-            chains = conn.get("chains") or []
-            actual = chains[-1] if chains else ""
-            chain_str = " → ".join(reversed(chains)) if chains else "?"
-            if actual.lower() == expected_proxy.lower():
-                return True, f" via {chain_str}"
-            return False, f" expected {expected_proxy}, got {actual or '?'}"
+        route = _route_from_connections(_api_connections(api_base, api_secret),
+                                        host)
+        if route.get("found"):
+            return route
         time.sleep(0.2)
-    return False, f" expected {expected_proxy}, no active connection found"
+    return {"found": False, "line": "?", "group": "", "chain": ""}
+
+
+def _route_matches_expected_proxy(route: dict,
+                                  expected_proxy: str) -> tuple[bool, str]:
+    """Validate an observed route's terminal policy group."""
+    if not expected_proxy:
+        return True, ""
+    if not route.get("found"):
+        return False, f" expected {expected_proxy}, no active connection found"
+
+    actual = str(route.get("group") or "")
+    if actual.lower() == expected_proxy.lower():
+        return True, ""
+    return False, f" expected {expected_proxy}, got {actual or '?'}"
+
+
+def _target_uses_expected_proxy(api_base: str, api_secret: str, url: str,
+                                expected_proxy: str) -> tuple[bool, str]:
+    if not urllib.parse.urlparse(url).hostname or not expected_proxy:
+        return True, ""
+    return _route_matches_expected_proxy(
+        _target_route(api_base, api_secret, url), expected_proxy)
+
+
+def _connectivity_line_value(mode: str) -> str:
+    """Return the default route-line label for one check target mode."""
+    if mode == "direct":
+        return "direct"
+    if mode == "proxy":
+        return "?"
+    return "-"
+
+
+def _append_route_column(line: str, route_line: str,
+                         route_chain: str = "") -> str:
+    """Append the observed route in the same style as Mihomo chains."""
+    value = route_chain or route_line or "-"
+    return f"{line}  {DIM}via{NC} {value:<32s}"
+
+
+def _dedupe_check_targets(targets: list) -> list:
+    """Drop exact duplicate connectivity targets from multiple plugins.
+
+    Builtin plugins load before user plugins. Keep the first target's display
+    order, but merge an expected_proxy from a duplicate if the first one lacks
+    it, so a stale user plugin cannot remove route validation by accident.
+    """
+    out = []
+    seen = {}
+    for target in targets:
+        key = (getattr(target, "name", ""),
+               getattr(target, "url", ""),
+               getattr(target, "mode", ""))
+        if key in seen:
+            kept = seen[key]
+            expected = getattr(target, "expected_proxy", "")
+            if expected and not getattr(kept, "expected_proxy", ""):
+                kept.expected_proxy = expected
+            continue
+        seen[key] = target
+        out.append(target)
+    return out
+
+
+def _dedupe_outbound_probes(probes: list) -> list:
+    """Drop exact duplicate outbound probes from multiple plugins."""
+    out = []
+    seen = set()
+    for probe in probes:
+        key = (getattr(probe, "name", ""),
+               getattr(probe, "mode", ""),
+               getattr(probe, "url", ""),
+               getattr(probe, "extract_re", ""))
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(probe)
+    return out
 
 
 def _test_dns(desc: str, server: str, domain: str) -> tuple:
@@ -716,7 +820,7 @@ def _collect_fail_hints(collector: dict, *, dns_bad: bool, failed: bool) -> list
     if basic.get("daemon_up") is False:
         hints.append("engine not running")
 
-    # connectivity: 列表形式，每项 {name, url, ok, message}
+    # connectivity: 列表形式，每项 {name, url, mode, line, route_chain, ok, message}
     conn = stages.get("connectivity") or []
     failed_conns = [c.get("name", "?") for c in conn
                     if isinstance(c, dict) and not c.get("ok")]
@@ -794,7 +898,8 @@ def cmd_check(engine, api: str, api_secret: str,
     # [4/4] 出口 IP 探测：从插件收集到的 probes 决定有哪些出口
     probes = []
     if registry is not None:
-        probes = registry.collect("check_outbound_probes", ctx={})
+        probes = _dedupe_outbound_probes(
+            registry.collect("check_outbound_probes", ctx={}))
     probe_ips: dict[str, str] = {p.name: "" for p in probes}
 
     # 临时常量：probes 在端口解析之前启动，所以这里用 config 直接拿
@@ -1051,7 +1156,8 @@ def cmd_check(engine, api: str, api_secret: str,
     ctx = {"corp_net": corp_net, "mode": mode, "engine": engine.name}
     targets = []
     if registry is not None:
-        targets = registry.collect("check_targets", ctx=ctx)
+        targets = _dedupe_check_targets(
+            registry.collect("check_targets", ctx=ctx))
 
     # 应用 only_when 过滤
     def _target_enabled(t):
@@ -1074,6 +1180,9 @@ def cmd_check(engine, api: str, api_secret: str,
     ready    = [threading.Event() for _ in targets]
 
     def _run_test(idx, target):
+        route_line = _connectivity_line_value(target.mode)
+        route_chain = ""
+        route_note = ""
         try:
             if target.mode == "dns":
                 # url 格式: dns:<server>:<domain>
@@ -1087,17 +1196,24 @@ def cmd_check(engine, api: str, api_secret: str,
                                      target.mode, target.timeout,
                                      proxy_port=proxy_port)
                 expected = getattr(target, "expected_proxy", "")
-                if ok and expected:
-                    route_ok, route_msg = _target_uses_expected_proxy(
-                        api, api_secret, target.url, expected)
-                    ok = route_ok
-                    if route_ok:
-                        line += f"  {GREEN}{route_msg}{NC}"
-                    else:
-                        line += f"  {RED}{route_msg}{NC}"
+                if target.mode == "proxy" and ok:
+                    route = _target_route(api, api_secret, target.url)
+                    route_line = str(route.get("line") or "?")
+                    route_chain = str(route.get("chain") or "")
+                    if expected:
+                        route_ok, route_msg = _route_matches_expected_proxy(
+                            route, expected)
+                        ok = route_ok
+                        if route_ok:
+                            route_note = f"  {GREEN}{route_msg}{NC}"
+                        else:
+                            route_note = f"  {RED}{route_msg}{NC}"
+            line = _append_route_column(line, route_line, route_chain)
+            line += route_note
         except Exception as e:
             ok, line = False, f"  {RED}✗{NC} {target.name}  error: {e}"
-        results[idx] = (line, ok)
+            line = _append_route_column(line, route_line, route_chain)
+        results[idx] = (line, ok, route_line, route_chain)
         ready[idx].set()
 
     if targets:
@@ -1106,7 +1222,7 @@ def cmd_check(engine, api: str, api_secret: str,
                 pool.submit(_run_test, idx, target)
             for idx in range(len(targets)):
                 ready[idx].wait()
-                line, ok = results[idx]
+                line, ok, route_line, route_chain = results[idx]
                 print(line)
                 if not ok:
                     fail = True
@@ -1114,6 +1230,8 @@ def cmd_check(engine, api: str, api_secret: str,
                     "name": targets[idx].name,
                     "url": targets[idx].url,
                     "mode": targets[idx].mode,
+                    "line": route_line,
+                    "route_chain": route_chain,
                     "ok": bool(ok),
                     "message": _strip_ansi(line),
                 })

{proxyctl-0.5.8 → proxyctl-0.5.9}/src/proxyctl/connections.py

@@ -87,6 +87,7 @@ class LocalConnection:
             "pid": self.pid,
             "fd": self.fd,
             "process": self.process,
+            "command": self.command,
             "app_contexts": _detect_app_contexts(self._match_text()),
             "local_source_port": self.source_port,
             "target_host": self.target_host,
@@ -163,6 +164,9 @@ class ConnectionArgs:
         agent_filters: Agent/tool filters from ``--agent``.
         query_filters: Free-text filters from ``--query`` / ``--filter``.
         all_apps: Whether ``--all`` was explicitly requested.
+        verbose: Whether ``--verbose`` was set — human view should expand
+            per-socket detail (rule / chains / upload / process / command /
+            match_reasons) instead of only the destination-group summary.
     """
 
     app_filters: list[str]
@@ -173,6 +177,7 @@ class ConnectionArgs:
     agent_filters: list[str] = field(default_factory=list)
     query_filters: list[str] = field(default_factory=list)
     all_apps: bool = False
+    verbose: bool = False
 
     def has_filters(self) -> bool:
         """Return whether any narrowing filter is active."""
@@ -194,6 +199,12 @@ def parse_args(args: list[str]) -> ConnectionArgs:
         ``--host`` / ``--chain`` / ``--route`` / ``--preset`` / ``--agent`` /
         ``--query`` are repeatable. ``--line`` aliases ``--chain``.
         ``--app`` is kept as a legacy alias for process/app filtering.
+
+    Positional keywords:
+        Any non-flag token (not starting with ``--``) is appended to
+        ``query_filters`` and behaves identically to ``--query <kw>``.
+        Multiple positional/--query keywords are combined with AND across
+        cross-field smart matching dimensions (IP/host, port, PID, process).
     """
     parsed = ConnectionArgs(app_filters=[])
     idx = 0
@@ -203,20 +214,27 @@ def parse_args(args: list[str]) -> ConnectionArgs:
             parsed.all_apps = True
             idx += 1
             continue
+        if arg == "--verbose":
+            parsed.verbose = True
+            idx += 1
+            continue
         if arg in ("--app", "--host", "--chain", "--line", "--route",
                    "--preset", "--agent",
                    "--query", "--filter"):
             _append_filter_arg(parsed, arg, args, idx)
             idx += 2
             continue
-        _io.fail(f"未识别 connections 参数：{arg}",
-                 hints=["proxyctl connections --host anthropic.com",
-                        "proxyctl connections --chain SG-Residential-01",
-                        "proxyctl connections --route proxy",
-                        "proxyctl connections --preset ai",
-                        "proxyctl connections --agent codex --json",
-                        "proxyctl connections --json"],
-                 doc="agent-protocol", code=_io.USAGE, cmd="connections")
+        if arg.startswith("--"):
+            _io.fail(f"未识别 connections 参数：{arg}",
+                     hints=["proxyctl connections codex",
+                            "proxyctl connections 443 anthropic",
+                            "proxyctl connections claude --verbose",
+                            "proxyctl connections --host anthropic.com",
+                            "proxyctl connections --preset ai",
+                            "proxyctl connections --json"],
+                     doc="agent-protocol", code=_io.USAGE, cmd="connections")
+        parsed.query_filters.append(arg)
+        idx += 1
     return parsed
 
 
@@ -665,7 +683,12 @@ def _proxy_owner_selection_reason(conn: dict[str, Any], owner: ProxyOwner,
 
 def _proxy_owner_item_matches_filters(item: dict[str, Any],
                                       args: ConnectionArgs) -> bool:
-    """Return whether a proxy-owner item satisfies active filters."""
+    """Return whether a proxy-owner item satisfies active filters.
+
+    Side effect: when keyword/--query filters match, the per-keyword
+    dimension hits are written into ``item["match_reasons"]`` so downstream
+    rendering (JSON, human highlight) can explain why the row was kept.
+    """
     owner = item.get("owner") or {}
     process_text = " ".join([
         str(owner.get("app") or ""),
@@ -675,32 +698,70 @@ def _proxy_owner_item_matches_filters(item: dict[str, Any],
     ])
     contexts = list(item.get("candidate_contexts") or [])
     contexts.extend(owner.get("app_contexts") or [])
-    detail = item.get("mihomo")
-    return _matches_filter_dimensions(
+    detail = item.get("mihomo") or {}
+    row_fields = {
+        "target_host": detail.get("host") or "",
+        "destination_ip": detail.get("destination_ip") or "",
+        "app": owner.get("app") or "",
+        "process": owner.get("process") or "",
+        "command": owner.get("command") or "",
+        "target_port": detail.get("destination_port") or item.get("target_port"),
+        "source_port": detail.get("source_port") or item.get("local_source_port"),
+        "pid": owner.get("pid"),
+    }
+    reasons = _matches_filter_dimensions(
         process_text, _detail_text(detail), contexts, args,
         chain_text=_chain_text(detail),
         route_kind=_route_kind_text(detail),
+        row_fields=row_fields,
     )
+    if reasons is None:
+        return False
+    if reasons:
+        item["match_reasons"] = reasons
+    return True
 
 
 def _local_item_matches_filters(item: dict[str, Any],
                                 args: ConnectionArgs) -> bool:
-    """Return whether a local lsof item satisfies active filters."""
+    """Return whether a local lsof item satisfies active filters.
+
+    Side effect: see ``_proxy_owner_item_matches_filters``.
+    """
     process_text = " ".join([
         str(item.get("app") or ""),
         os.path.basename(str(item.get("process") or "")),
         str(item.get("process") or ""),
+        str(item.get("command") or ""),
     ])
     target_text = " ".join([
         str(item.get("target_host") or ""),
         _detail_text(item.get("mihomo")),
     ])
-    detail = item.get("mihomo")
-    return _matches_filter_dimensions(
+    detail = item.get("mihomo") or {}
+    # When mihomo joined this socket, prefer its host/destination_ip over the
+    # lsof-side target (which for proxy traffic is just 127.0.0.1:7890).
+    row_fields = {
+        "target_host": detail.get("host") or item.get("target_host") or "",
+        "destination_ip": detail.get("destination_ip") or "",
+        "app": item.get("app") or "",
+        "process": item.get("process") or "",
+        "command": item.get("command") or "",
+        "target_port": detail.get("destination_port") or item.get("target_port"),
+        "source_port": item.get("local_source_port"),
+        "pid": item.get("pid"),
+    }
+    reasons = _matches_filter_dimensions(
         process_text, target_text, item.get("app_contexts") or [], args,
         chain_text=_chain_text(detail),
         route_kind=_route_kind_text(detail),
+        row_fields=row_fields,
     )
+    if reasons is None:
+        return False
+    if reasons:
+        item["match_reasons"] = reasons
+    return True
 
 
 def _proxy_group_key(item: dict[str, Any]) -> tuple[str, str]:
@@ -851,6 +912,10 @@ def build_report(backend_name: str, config: dict[str, Any],
     proxy_owner_rows = _proxy_owner_connections(
         remote_rows, proxy_port, parsed_args)
     proxy_owner_group_rows = _proxy_owner_groups(proxy_owner_rows)
+    history_status: dict[str, Any] = {"loaded": False}
+    if parsed_args.verbose:
+        history_status = _attach_history_to_rows(
+            config, joined, proxy_owner_rows)
     return {
         "proxy_port": proxy_port,
         "backend": backend_name,
@@ -865,6 +930,8 @@ def build_report(backend_name: str, config: dict[str, Any],
             "query": parsed_args.query_filters,
         },
         "all_apps": parsed_args.all_apps,
+        "verbose": parsed_args.verbose,
+        "history_status": history_status,
         "api": api_status,
         "connections": joined,
         "proxy_owner_connections": proxy_owner_rows,
@@ -891,6 +958,84 @@ def build_report(backend_name: str, config: dict[str, Any],
     }
 
 
+def _attach_history_to_rows(config: dict[str, Any],
+                            local_rows: list[dict[str, Any]],
+                            proxy_owner_rows: list[dict[str, Any]]
+                            ) -> dict[str, Any]:
+    """Load traffic-store events and attach per-host history to each row.
+
+    Returns a small status dict that the human renderer can inspect to
+    decide whether to print a "history is empty — run traffic sample first"
+    hint. JSON consumers see the same status under report["history_status"].
+    """
+    from proxyctl import traffic_store
+    paths = traffic_store.store_paths(config, None)
+    events = traffic_store.read_events(paths["events_path"])
+    status: dict[str, Any] = {
+        "loaded": True,
+        "events_path": paths["events_path"],
+        "event_count": len(events),
+        "exists": os.path.exists(paths["events_path"]),
+    }
+    if not events:
+        return status
+    by_host: dict[str, list[dict[str, Any]]] = {}
+    for ev in events:
+        host_key = str(ev.get("host") or ev.get("destination_ip") or "")
+        if not host_key:
+            continue
+        by_host.setdefault(host_key, []).append(ev)
+    for row_list in (local_rows, proxy_owner_rows):
+        for item in row_list:
+            host = ""
+            mihomo = item.get("mihomo") or {}
+            host = (mihomo.get("host")
+                    or mihomo.get("destination_ip")
+                    or item.get("target_host") or "")
+            host = str(host)
+            if not host:
+                continue
+            matched = by_host.get(host)
+            if matched:
+                item["history"] = _summarize_history_events(matched)
+    return status
+
+
+def _summarize_history_events(events: list[dict[str, Any]]) -> dict[str, Any]:
+    """Aggregate traffic-store events for one host into a compact summary."""
+    upload_total = 0
+    download_total = 0
+    sample_times: list[str] = []
+    owner_apps: set[str] = set()
+    connection_keys: set[str] = set()
+    for ev in events:
+        try:
+            upload_total += int(ev.get("upload") or 0)
+            download_total += int(ev.get("download") or 0)
+        except (TypeError, ValueError):
+            pass
+        ts = ev.get("sample_ts")
+        if isinstance(ts, str) and ts:
+            sample_times.append(ts)
+        attribution = ev.get("attribution") or {}
+        app_name = attribution.get("app") or attribution.get("owner_app")
+        if app_name:
+            owner_apps.add(str(app_name))
+        key = ev.get("state_key") or ev.get("id")
+        if key:
+            connection_keys.add(str(key))
+    sample_times.sort()
+    return {
+        "event_count": len(events),
+        "upload_total": upload_total,
+        "download_total": download_total,
+        "first_seen": sample_times[0] if sample_times else "",
+        "last_seen": sample_times[-1] if sample_times else "",
+        "owner_apps": sorted(owner_apps),
+        "connection_count": len(connection_keys),
+    }
+
+
 def emit_human(report: dict[str, Any]) -> None:
     """Render a compact human-readable report via the human renderer."""
     from proxyctl.connections_human import emit_human as render_human