Aether/_deprecated_py_src/clients/http_client.py

"""
全局HTTP客户端池管理
避免每次请求都创建新的AsyncClient,提高性能

性能优化说明：
1. 默认客户端：无代理场景，全局复用单一客户端
2. 代理客户端缓存：相同代理配置复用同一客户端，避免重复创建
3. 连接池复用：Keep-alive 连接减少 TCP 握手开销
"""

from __future__ import annotations

import asyncio
import os
import time
from contextlib import asynccontextmanager
from typing import Any

import httpx

from src.config import config
from src.core.logger import logger
from src.services.proxy_node.resolver import (
    build_proxy_url_async,
    compute_proxy_cache_key,
    get_system_proxy_config_async,
    make_proxy_param,
    resolve_delegate_config_async,
)
from src.utils.ssl_utils import get_ssl_context, get_ssl_context_for_profile

# 模块级锁，避免类属性延迟初始化的竞态条件
_proxy_clients_lock = asyncio.Lock()
_default_client_lock = asyncio.Lock()


def _get_int_env(name: str, default: int, minimum: int) -> int:
    """Read positive integer env value with bounds and fallback."""
    raw = os.getenv(name)
    if raw is None:
        return default
    try:
        value = int(raw)
    except ValueError:
        logger.warning("环境变量 {} 不是有效整数: {}, 使用默认值 {}", name, raw, default)
        return default
    return max(minimum, value)


class HTTPClientPool:
    """
    全局HTTP客户端池单例

    管理可重用的httpx.AsyncClient实例,避免频繁创建/销毁连接

    性能优化：
    1. 默认客户端：无代理场景复用
    2. 代理客户端缓存：相同代理配置复用同一客户端
    3. LRU 淘汰：代理客户端超过上限时淘汰最久未使用的
    """

    _instance: HTTPClientPool | None = None
    _default_client: httpx.AsyncClient | None = None
    _clients: dict[str, httpx.AsyncClient] = {}
    _max_named_clients: int = 20
    # 代理客户端缓存：{cache_key: (client, last_used_time)}
    _proxy_clients: dict[str, tuple[httpx.AsyncClient, float]] = {}
    # 代理客户端缓存上限（避免内存泄漏）
    _max_proxy_clients: int = 50
    # Tunnel 客户端缓存：{node_id: (client, last_used_time)}
    _tunnel_clients: dict[str, tuple[httpx.AsyncClient, float]] = {}
    _max_tunnel_clients: int = 30
    # 后台清理任务引用集合（防止被 GC 回收）
    _background_tasks: set[asyncio.Task[None]] = set()

    def __new__(cls) -> "HTTPClientPool":
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance

    @classmethod
    async def get_default_client_async(cls) -> httpx.AsyncClient:
        """
        获取默认的HTTP客户端（异步线程安全版本）

        用于大多数HTTP请求,具有合理的默认配置
        """
        if cls._default_client is not None:
            return cls._default_client

        async with _default_client_lock:
            # 双重检查，避免重复创建
            if cls._default_client is None:
                cls._default_client = httpx.AsyncClient(
                    http2=config.enable_http2,
                    verify=get_ssl_context(),  # 使用 certifi 证书
                    timeout=httpx.Timeout(
                        connect=config.http_connect_timeout,
                        read=config.http_read_timeout,
                        write=config.http_write_timeout,
                        pool=config.http_pool_timeout,
                    ),
                    limits=httpx.Limits(
                        max_connections=config.http_max_connections,
                        max_keepalive_connections=config.http_keepalive_connections,
                        keepalive_expiry=config.http_keepalive_expiry,
                    ),
                    follow_redirects=True,  # 跟随重定向
                )
                logger.info(
                    "全局HTTP客户端池已初始化: max_connections={}, keepalive={}, keepalive_expiry={}s",
                    config.http_max_connections,
                    config.http_keepalive_connections,
                    config.http_keepalive_expiry,
                )
        return cls._default_client

    @classmethod
    def get_default_client(cls) -> httpx.AsyncClient:
        """
        获取默认的HTTP客户端（同步版本，向后兼容）

        ⚠️ 注意：此方法在高并发首次调用时可能存在竞态条件，
        推荐使用 get_default_client_async() 异步版本。
        """
        if cls._default_client is None:
            cls._default_client = httpx.AsyncClient(
                http2=config.enable_http2,
                verify=get_ssl_context(),  # 使用 certifi 证书
                timeout=httpx.Timeout(
                    connect=config.http_connect_timeout,
                    read=config.http_read_timeout,
                    write=config.http_write_timeout,
                    pool=config.http_pool_timeout,
                ),
                limits=httpx.Limits(
                    max_connections=config.http_max_connections,
                    max_keepalive_connections=config.http_keepalive_connections,
                    keepalive_expiry=config.http_keepalive_expiry,
                ),
                follow_redirects=True,  # 跟随重定向
            )
            logger.info(
                "全局HTTP客户端池已初始化: max_connections={}, keepalive={}, keepalive_expiry={}s",
                config.http_max_connections,
                config.http_keepalive_connections,
                config.http_keepalive_expiry,
            )
        return cls._default_client

    @classmethod
    def get_client(cls, name: str, **kwargs: Any) -> httpx.AsyncClient:
        """
        获取或创建命名的HTTP客户端

        用于需要特定配置的场景(如不同的超时设置、代理等)

        Args:
            name: 客户端标识符
            **kwargs: httpx.AsyncClient的配置参数
        """
        if name in cls._clients:
            # 命中缓存：移到末尾以维护 LRU 顺序
            cls._clients[name] = cls._clients.pop(name)
            return cls._clients[name]

        # 淘汰最久未使用的客户端（dict 头部即 LRU）
        if len(cls._clients) >= cls._max_named_clients:
            oldest_name = next(iter(cls._clients))
            old_client = cls._clients.pop(oldest_name)
            try:
                asyncio.get_running_loop().create_task(old_client.aclose())
            except RuntimeError:
                pass
            logger.debug("淘汰命名HTTP客户端: {}", oldest_name)

        # 合并默认配置和自定义配置
        default_config = {
            "http2": config.enable_http2,
            "verify": get_ssl_context(),
            "timeout": httpx.Timeout(
                connect=config.http_connect_timeout,
                read=config.http_read_timeout,
                write=config.http_write_timeout,
                pool=config.http_pool_timeout,
            ),
            "follow_redirects": True,
        }
        default_config.update(kwargs)

        cls._clients[name] = httpx.AsyncClient(**default_config)  # type: ignore[arg-type]
        logger.debug("创建命名HTTP客户端: {}", name)

        return cls._clients[name]

    @classmethod
    def _get_proxy_clients_lock(cls) -> asyncio.Lock:
        """获取代理客户端缓存锁（模块级单例，避免竞态条件）"""
        return _proxy_clients_lock

    @classmethod
    async def _evict_lru_proxy_client(cls) -> None:
        """淘汰最久未使用的代理客户端"""
        if len(cls._proxy_clients) < cls._max_proxy_clients:
            return

        # 找到最久未使用的客户端
        oldest_key = min(cls._proxy_clients.keys(), key=lambda k: cls._proxy_clients[k][1])
        old_client, _ = cls._proxy_clients.pop(oldest_key)

        # 异步关闭旧客户端
        try:
            await old_client.aclose()
            logger.debug("淘汰代理客户端: {}", oldest_key)
        except Exception as e:
            logger.warning("关闭代理客户端失败: {}", e)

    @classmethod
    async def get_proxy_client(
        cls,
        proxy_config: dict[str, Any] | None = None,
        tls_profile: str | None = None,
    ) -> httpx.AsyncClient:
        """
        获取代理客户端（带缓存复用）

        相同代理配置会复用同一个客户端，大幅减少连接建立开销。
        当 proxy_config 为 None 时，自动回退到系统默认代理节点。
        注意：返回的客户端使用默认超时配置，如需自定义超时请在请求时传递 timeout 参数。

        Args:
            proxy_config: 代理配置字典，为 None 时使用系统默认代理

        Returns:
            可复用的 httpx.AsyncClient 实例
        """
        # 无特定代理时，回退到系统默认代理
        if not proxy_config:
            proxy_config = await get_system_proxy_config_async()

        delegate_cfg = await resolve_delegate_config_async(proxy_config)
        if delegate_cfg and delegate_cfg.get("tunnel"):
            return await cls._get_tunnel_client(delegate_cfg["node_id"])

        cache_key = compute_proxy_cache_key(proxy_config)
        tls_profile_key = str(tls_profile or "").strip().lower()
        if tls_profile_key:
            cache_key = f"{cache_key}::tls:{tls_profile_key}"

        # 无代理时返回默认客户端
        if cache_key == "__no_proxy__":
            return await cls.get_default_client_async()

        lock = cls._get_proxy_clients_lock()
        async with lock:
            # 检查缓存
            if cache_key in cls._proxy_clients:
                client, _ = cls._proxy_clients[cache_key]
                # 健康检查：如果客户端已关闭，移除并重新创建
                if client.is_closed:
                    del cls._proxy_clients[cache_key]
                    logger.debug("代理客户端已关闭，将重新创建: {}", cache_key)
                else:
                    # 更新最后使用时间
                    cls._proxy_clients[cache_key] = (client, time.time())
                    if tls_profile_key:
                        logger.debug(
                            "复用代理客户端 TLS profile={} key={}", tls_profile_key, cache_key
                        )
                    return client

            # 淘汰旧客户端（如果超过上限）
            await cls._evict_lru_proxy_client()

            # 添加代理配置
            proxy_url = await build_proxy_url_async(proxy_config) if proxy_config else None

            # curl_cffi Transport: real TLS fingerprint impersonation.
            # Supports:
            # - "claude_code_nodejs" (legacy alias, uses default chrome120 impersonate)
            # - direct chrome impersonate profile names (e.g. "chrome124")
            use_curl_cffi_tls = False
            if tls_profile_key:
                from src.services.provider.fingerprint import KNOWN_IMPERSONATE_PROFILES

                use_curl_cffi_tls = (
                    tls_profile_key == "claude_code_nodejs"
                    or tls_profile_key in KNOWN_IMPERSONATE_PROFILES
                )

            if use_curl_cffi_tls:
                from src.clients.curl_cffi_transport import (
                    CURL_CFFI_AVAILABLE,
                    CurlCffiTransport,
                )

                if CURL_CFFI_AVAILABLE:
                    transport_kwargs: dict[str, Any] = {"proxy": proxy_url}
                    if tls_profile_key != "claude_code_nodejs":
                        transport_kwargs["impersonate"] = tls_profile_key

                    transport = CurlCffiTransport(**transport_kwargs)
                    client = httpx.AsyncClient(
                        transport=transport,
                        follow_redirects=True,
                        timeout=httpx.Timeout(
                            connect=config.http_connect_timeout,
                            read=config.http_read_timeout,
                            write=config.http_write_timeout,
                            pool=config.http_pool_timeout,
                        ),
                    )
                    cls._proxy_clients[cache_key] = (client, time.time())
                    logger.info(
                        "创建 curl_cffi TLS 指纹客户端: profile={}, proxy={}",
                        tls_profile_key,
                        proxy_url or "direct",
                    )
                    return client
                else:
                    logger.warning(
                        "curl_cffi 不可用，回退到 best-effort TLS 配置 (profile={})",
                        tls_profile_key,
                    )

            # 创建新客户端（使用默认超时，请求时可覆盖）
            client_config: dict[str, Any] = {
                "http2": config.enable_http2,
                "verify": get_ssl_context_for_profile(tls_profile),
                "follow_redirects": True,
                "limits": httpx.Limits(
                    max_connections=config.http_max_connections,
                    max_keepalive_connections=config.http_keepalive_connections,
                    keepalive_expiry=config.http_keepalive_expiry,
                ),
                "timeout": httpx.Timeout(
                    connect=config.http_connect_timeout,
                    read=config.http_read_timeout,
                    write=config.http_write_timeout,
                    pool=config.http_pool_timeout,
                ),
            }

            proxy_param = make_proxy_param(proxy_url)
            if proxy_param:
                client_config["proxy"] = proxy_param

            client = httpx.AsyncClient(**client_config)  # type: ignore[arg-type]
            cls._proxy_clients[cache_key] = (client, time.time())

            proxy_label = "none"
            if proxy_config:
                proxy_label = str(
                    proxy_config.get("node_id") or proxy_config.get("url") or "unknown"
                )
            logger.debug(
                "创建代理客户端(缓存): {}, 缓存数量: {}", proxy_label, len(cls._proxy_clients)
            )
            if tls_profile_key:
                logger.debug("创建代理客户端 TLS profile={} key={}", tls_profile_key, cache_key)

            return client

    @classmethod
    async def close_all(cls) -> None:
        """关闭所有HTTP客户端"""
        if cls._default_client is not None:
            await cls._default_client.aclose()
            cls._default_client = None
            logger.info("默认HTTP客户端已关闭")

        for name, client in cls._clients.items():
            await client.aclose()
            logger.debug("命名HTTP客户端已关闭: {}", name)

        cls._clients.clear()

        # 关闭代理客户端缓存
        for cache_key, (client, _) in cls._proxy_clients.items():
            try:
                await client.aclose()
                logger.debug("代理客户端已关闭: {}", cache_key)
            except Exception as e:
                logger.warning("关闭代理客户端失败: {}", e)

        cls._proxy_clients.clear()

        # 关闭 tunnel 客户端缓存
        for nid, (client, _) in cls._tunnel_clients.items():
            try:
                await client.aclose()
                logger.debug("tunnel 客户端已关闭: {}", nid)
            except Exception as e:
                logger.warning("关闭 tunnel 客户端失败: {}", e)

        cls._tunnel_clients.clear()

        # 关闭 curl_cffi session 缓存
        try:
            from src.clients.curl_cffi_transport import CURL_CFFI_AVAILABLE, close_all_sessions

            if CURL_CFFI_AVAILABLE:
                await close_all_sessions()
                logger.debug("curl_cffi sessions 已关闭")
        except Exception as e:
            logger.debug("关闭 curl_cffi sessions 失败: {}", e)

        logger.info("所有HTTP客户端已关闭")

    @classmethod
    async def cleanup_idle_clients(
        cls,
        max_idle_seconds: int | None = None,
    ) -> dict[str, int]:
        """清理空闲的代理/Tunnel 客户端并关闭连接池资源。"""
        idle_seconds = max_idle_seconds
        if idle_seconds is None:
            idle_seconds = _get_int_env("HTTP_CLIENT_IDLE_CLEANUP_MAX_SECONDS", 600, minimum=60)

        now = time.time()
        stale_proxy_clients: list[tuple[str, httpx.AsyncClient]] = []
        stale_tunnel_clients: list[tuple[str, httpx.AsyncClient]] = []
        removed_closed_proxy = 0
        removed_closed_tunnel = 0

        lock = cls._get_proxy_clients_lock()
        async with lock:
            for cache_key, (client, last_used) in list(cls._proxy_clients.items()):
                if client.is_closed:
                    cls._proxy_clients.pop(cache_key, None)
                    removed_closed_proxy += 1
                    continue
                if now - last_used > idle_seconds:
                    entry = cls._proxy_clients.pop(cache_key, None)
                    if entry is not None:
                        stale_proxy_clients.append((cache_key, entry[0]))

            for node_id, (client, last_used) in list(cls._tunnel_clients.items()):
                if client.is_closed:
                    cls._tunnel_clients.pop(node_id, None)
                    removed_closed_tunnel += 1
                    continue
                if now - last_used > idle_seconds:
                    entry = cls._tunnel_clients.pop(node_id, None)
                    if entry is not None:
                        stale_tunnel_clients.append((node_id, entry[0]))

        proxy_closed = 0
        tunnel_closed = 0
        for cache_key, client in stale_proxy_clients:
            try:
                await client.aclose()
                proxy_closed += 1
            except Exception as e:
                logger.warning("关闭空闲代理客户端失败(key={}): {}", cache_key, e)

        for node_id, client in stale_tunnel_clients:
            try:
                await client.aclose()
                tunnel_closed += 1
            except Exception as e:
                logger.warning("关闭空闲 Tunnel 客户端失败(node_id={}): {}", node_id, e)

        if proxy_closed or tunnel_closed or removed_closed_proxy or removed_closed_tunnel:
            logger.info(
                "HTTP 客户端空闲清理完成: proxy_closed={}, tunnel_closed={}, "
                "proxy_already_closed={}, tunnel_already_closed={}, idle_seconds={}",
                proxy_closed,
                tunnel_closed,
                removed_closed_proxy,
                removed_closed_tunnel,
                idle_seconds,
            )

        return {
            "proxy_closed": proxy_closed,
            "tunnel_closed": tunnel_closed,
            "proxy_already_closed": removed_closed_proxy,
            "tunnel_already_closed": removed_closed_tunnel,
        }

    @classmethod
    @asynccontextmanager
    async def get_temp_client(cls, **kwargs: Any) -> Any:
        """
        获取临时HTTP客户端(上下文管理器)

        用于一次性请求,使用后自动关闭

        用法:
            async with HTTPClientPool.get_temp_client() as client:
                response = await client.get('https://example.com')
        """
        default_config = {
            "http2": config.enable_http2,
            "verify": get_ssl_context(),
            "timeout": httpx.Timeout(
                connect=config.http_connect_timeout,
                read=config.http_read_timeout,
                write=config.http_write_timeout,
                pool=config.http_pool_timeout,
            ),
        }
        default_config.update(kwargs)

        client = httpx.AsyncClient(**default_config)  # type: ignore[arg-type]
        try:
            yield client
        finally:
            await client.aclose()

    @classmethod
    async def _reset_default_client(cls) -> bool:
        """Atomically replace the shared default client with a fresh instance.

        The old client is kept open briefly so that in-flight requests can
        finish on their existing HTTP/2 streams; it is closed asynchronously
        after a short grace period.
        """
        async with _default_client_lock:
            old_client = cls._default_client
            if old_client is None:
                return False

            # Create a new client before discarding the old one
            cls._default_client = httpx.AsyncClient(
                http2=config.enable_http2,
                verify=get_ssl_context(),
                timeout=httpx.Timeout(
                    connect=config.http_connect_timeout,
                    read=config.http_read_timeout,
                    write=config.http_write_timeout,
                    pool=config.http_pool_timeout,
                ),
                limits=httpx.Limits(
                    max_connections=config.http_max_connections,
                    max_keepalive_connections=config.http_keepalive_connections,
                    keepalive_expiry=config.http_keepalive_expiry,
                ),
                follow_redirects=True,
            )

        # Close old client after a grace period so in-flight requests can drain
        async def _close_old() -> None:
            await asyncio.sleep(5)
            try:
                await old_client.aclose()
            except Exception as exc:
                logger.warning("关闭旧默认客户端失败: {}", exc)

        task = asyncio.create_task(_close_old())
        cls._background_tasks.add(task)
        task.add_done_callback(cls._background_tasks.discard)
        logger.warning("默认HTTP客户端已重建(HTTP/2 流容量恢复)")
        return True

    @classmethod
    async def reset_upstream_client(
        cls,
        delegate_cfg: dict[str, Any] | None,
        proxy_config: dict[str, Any] | None = None,
        tls_profile: str | None = None,
    ) -> bool:
        """Reset cached upstream client for the given proxy/tunnel route.

        Returns True when a cached client was closed and removed.
        For the shared no-proxy default client, atomically replaces it with a
        new instance so that subsequent requests get a fresh HTTP/2 connection
        while in-flight requests on the old client can finish naturally.
        """
        if delegate_cfg and delegate_cfg.get("tunnel"):
            node_id = str(delegate_cfg.get("node_id") or "")
            if not node_id:
                return False
            lock = cls._get_proxy_clients_lock()
            async with lock:
                entry = cls._tunnel_clients.pop(node_id, None)
            if entry is None:
                return False
            client, _ = entry
            try:
                await client.aclose()
            except Exception as exc:
                logger.warning("关闭 Tunnel 客户端失败(node_id={}): {}", node_id, exc)
            return True

        if not proxy_config:
            proxy_config = await get_system_proxy_config_async()

        base_cache_key = compute_proxy_cache_key(proxy_config)
        if base_cache_key == "__no_proxy__":
            return await cls._reset_default_client()

        cache_key_prefixes = [base_cache_key]
        tls_profile_key = str(tls_profile or "").strip().lower()
        if tls_profile_key:
            cache_key_prefixes = [f"{base_cache_key}::tls:{tls_profile_key}"]

        lock = cls._get_proxy_clients_lock()
        async with lock:
            keys_to_remove = [
                key
                for key in list(cls._proxy_clients.keys())
                if any(
                    key == prefix
                    or key.startswith(f"{prefix}::")
                    or key.startswith(f"{prefix}::tls:")
                    for prefix in cache_key_prefixes
                )
            ]
            clients = [cls._proxy_clients.pop(key)[0] for key in keys_to_remove]

        for client in clients:
            try:
                await client.aclose()
            except Exception as exc:
                logger.warning("关闭上游代理客户端失败: {}", exc)

        return bool(clients)

    @classmethod
    async def get_upstream_client(
        cls,
        delegate_cfg: dict[str, Any] | None,
        proxy_config: dict[str, Any] | None = None,
        tls_profile: str | None = None,
    ) -> httpx.AsyncClient:
        """
        获取可复用的上游请求客户端（自动选择 tunnel/代理模式）

        tunnel 模式(delegate_cfg.tunnel=True)：返回 TunnelTransport 客户端
        直连/代理模式：返回代理客户端（含系统默认代理回退）
        """
        if delegate_cfg and delegate_cfg.get("tunnel"):
            return await cls._get_tunnel_client(delegate_cfg["node_id"])
        return await cls.get_proxy_client(proxy_config=proxy_config, tls_profile=tls_profile)

    @classmethod
    async def create_upstream_stream_client(
        cls,
        delegate_cfg: dict[str, Any] | None,
        proxy_config: dict[str, Any] | None = None,
        timeout: httpx.Timeout | None = None,
        tls_profile: str | None = None,
    ) -> httpx.AsyncClient:
        """
        创建上游流式请求客户端（自动选择 tunnel/代理模式）

        调用者需负责关闭返回的客户端。
        """
        if delegate_cfg and delegate_cfg.get("tunnel"):
            return await cls._get_tunnel_client(delegate_cfg["node_id"], timeout=timeout)
        client_config: dict[str, Any] = {
            "http2": config.enable_http2,
            "verify": get_ssl_context_for_profile(tls_profile),
            "follow_redirects": True,
        }
        if timeout:
            client_config["timeout"] = timeout
        else:
            client_config["timeout"] = httpx.Timeout(
                connect=config.http_connect_timeout,
                read=config.http_read_timeout,
                write=config.http_write_timeout,
                pool=config.http_pool_timeout,
            )

        resolved_proxy_config = proxy_config
        if resolved_proxy_config is None:
            resolved_proxy_config = await get_system_proxy_config_async()

        proxy_url = (
            await build_proxy_url_async(resolved_proxy_config) if resolved_proxy_config else None
        )
        proxy_param = make_proxy_param(proxy_url)
        if proxy_param:
            client_config["proxy"] = proxy_param
            logger.debug(
                "创建带代理的HTTP客户端(一次性): {}",
                resolved_proxy_config.get("url", "unknown") if resolved_proxy_config else "unknown",
            )

        return httpx.AsyncClient(**client_config)

    @classmethod
    async def _get_tunnel_client(
        cls,
        node_id: str,
        timeout: httpx.Timeout | None = None,
    ) -> httpx.AsyncClient:
        """获取使用 TunnelTransport 的 httpx 客户端

        当 timeout 为 None 时（非流式请求），返回按 node_id 缓存的 client，
        调用方不应关闭此 client，其生命周期由 HTTPClientPool 管理。
        当 timeout 非 None 时（流式请求），每次创建新 client，由调用方负责关闭。
        """
        from src.services.proxy_node.tunnel_transport import create_tunnel_transport

        t = timeout or httpx.Timeout(
            connect=config.http_connect_timeout,
            read=config.http_read_timeout,
            write=config.http_write_timeout,
            pool=config.http_pool_timeout,
        )
        timeout_secs = t.read if isinstance(t, httpx.Timeout) else 60.0

        # 流式请求：每次创建新 client（调用方负责关闭）
        if timeout is not None:
            transport = create_tunnel_transport(node_id, timeout=timeout_secs or 60.0)
            return httpx.AsyncClient(transport=transport, timeout=t)

        # 非流式请求：复用缓存的 client（加锁与 proxy_clients 保持一致）
        lock = cls._get_proxy_clients_lock()
        async with lock:
            entry = cls._tunnel_clients.get(node_id)
            if entry is not None:
                existing, _ = entry
                if not existing.is_closed:
                    cls._tunnel_clients[node_id] = (existing, time.time())
                    return existing
                del cls._tunnel_clients[node_id]

            # 淘汰最久未使用的 tunnel 客户端
            if len(cls._tunnel_clients) >= cls._max_tunnel_clients:
                oldest_nid = min(cls._tunnel_clients, key=lambda k: cls._tunnel_clients[k][1])
                old_client, _ = cls._tunnel_clients.pop(oldest_nid)
                try:
                    await old_client.aclose()
                except Exception:
                    pass
                logger.debug("淘汰 tunnel 客户端: {}", oldest_nid)

            transport = create_tunnel_transport(node_id, timeout=timeout_secs or 60.0)
            client = httpx.AsyncClient(transport=transport, timeout=t)
            cls._tunnel_clients[node_id] = (client, time.time())
            return client

    @classmethod
    def get_pool_stats(cls) -> dict[str, Any]:
        """获取连接池统计信息"""
        return {
            "default_client_active": cls._default_client is not None,
            "named_clients_count": len(cls._clients),
            "proxy_clients_count": len(cls._proxy_clients),
            "max_proxy_clients": cls._max_proxy_clients,
            "tunnel_clients_count": len(cls._tunnel_clients),
        }


# 便捷访问函数
def get_http_client() -> httpx.AsyncClient:
    """获取默认HTTP客户端的便捷函数"""
    return HTTPClientPool.get_default_client()


async def close_http_clients() -> None:
    """关闭所有HTTP客户端的便捷函数"""
    await HTTPClientPool.close_all()