remote-cmd-manager 2.5.0__tar.gz → 2.7.0__tar.gz

{remote_cmd_manager-2.5.0/remote_cmd_manager.egg-info → remote_cmd_manager-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remote_cmd_manager
-Version: 2.5.0
+Version: 2.7.0
 Summary: Cross-platform SSH remote server management tool (Linux/macOS/Windows) — lightweight, zero-configuration CLI and Python API for managing servers over SSH. Supports host CRUD, batch commands, file transfer, credential encryption, async execution, and more.
 Author-email: Vae-Scrooge <vaescrooge@gmail.com>
 License: MIT
@@ -89,36 +89,36 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.5.0 Release Highlights
+## v2.7.0 Release Highlights
 
-v2.5.0 is a hardening and scalability release: dependency security floors, Python 3.9
-removal, bounded async scheduling, and explicit output-retention / credential-persistence
-policies. Backward-compatible defaults are preserved where behavior is involved. See the
-[full migration notes](./CHANGELOG.md) before upgrading automated callers.
+v2.7.0 is a runtime-efficiency and error-semantics release: credential-layer
+exceptions are narrowed so real bugs surface, SQLite no longer truncates its WAL
+on every write, and the global connection budget waits on a true async queue
+instead of polling. Public APIs remain backward compatible. See the
+[full migration notes](./CHANGELOG.md).
 
-### Security & Platform
+### Error Semantics
 
-- Minimum supported Python is now **3.10** (3.9 reached EOL on 2025-10-31).
-- Security floors raised: **Paramiko >= 5.0,<6** and **AsyncSSH >= 2.24.0,<3** (2.23.x and earlier are affected by 2026 AsyncSSH advisories).
+- Keyring, encryption, and host-service decrypt paths now catch only expected failure classes; programming errors propagate instead of being silently swallowed.
+- Background pool monitor loops keep their catch-all guard but log full stack traces.
+- Optional `asyncssh` detection uses `find_spec`, so a defect in the async modules themselves can no longer masquerade as "dependency not installed".
 
-### Scalability
+### SQLite WAL Efficiency
 
-- `AsyncBatchExecutor` now uses a **bounded worker queue**: only `min(max_concurrency, host count)` worker tasks are created instead of one task per host, so scheduling memory no longer grows with fleet size.
-- New `OutputPolicy` (exported from `remote_cmd`) gives an explicit, mutually exclusive alternative to `max_output_bytes`; `None` still means full retention in v2.5, and a bounded default is planned for v3.0.
+- `flush()` now runs a **PASSIVE** checkpoint instead of `TRUNCATE` — no more writer waits or WAL rewrites on every host add/update/remove.
+- New explicit `repo.checkpoint("TRUNCATE")` (also `PASSIVE`/`FULL`/`RESTART`) for deliberate WAL compaction.
 
-### Credential Safety
+### Connection Budget
 
-- `JsonHostRepository` / `SqliteHostRepository` accept `allow_plaintext_credentials` (default `None`): plaintext persistence now emits `PlaintextCredentialWarning`; pass `True` to opt in silently or `False` to reject it with `CredentialError`. v3.0 plans to reject by default.
-- JSON repository concurrency semantics are now explicit: single-process/single-writer; use SQLite for multi-process writers.
-- The `dev` extra now includes `asyncssh`, so `pip install -e ".[dev]"` runs the full test suite out of the box.
+- `ConnectionBudget.acquire_async()` now waits on a real queue (`asyncio.Future` woken via `call_soon_threadsafe`), removing the v2.6 polling loop; cancellation-safe and FIFO among async waiters.
 
-### Compatibility
+### Benchmark Data (P2.4)
 
-- `max_output_bytes=None` still retains full output, and the public `BatchResult` / `BatchHostResult` schemas are unchanged; the legacy `max_output_bytes` parameter continues to work alongside `OutputPolicy`.
+- The sync Paramiko path costs ~100 µs per command in thread create/join and peaks at ≈ 3× sustained concurrency in live threads. A centralized channel-reader rewrite is a v2.7.x decision based on these measurements.
 
 ## Table of Contents
 
-- [v2.5.0 Release Highlights](#v250-release-highlights)
+- [v2.7.0 Release Highlights](#v270-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -268,6 +268,7 @@ with SSHClient(config) as client:
 | **Tag System** | Filter hosts by tag (e.g., `production`, `web`, `db`) |
 | **Batch Ops** | Run commands across any host group, synchronously or asynchronously; optional per-host retained-output cap (`max_output_bytes`) |
 | **Async Kernel** | `AsyncSSHClient` / `AsyncConnectionPool` / `AsyncBatchExecutor` via the `[async]` extra |
+| **Global Connection Budget** | Optional `ConnectionBudget` caps live SSH connections process-wide across pools and executors |
 | **Task Runner** | Track and schedule long-running remote tasks with statuses (`TaskRunner`) |
 | **Connection Test** | Test all host SSH connections and report status |
 | **Secure Logging** | Structured logging that filters sensitive data (`SensitiveDataFilter`) |

{remote_cmd_manager-2.5.0 → remote_cmd_manager-2.7.0}/README.md

@@ -36,36 +36,36 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.5.0 Release Highlights
+## v2.7.0 Release Highlights
 
-v2.5.0 is a hardening and scalability release: dependency security floors, Python 3.9
-removal, bounded async scheduling, and explicit output-retention / credential-persistence
-policies. Backward-compatible defaults are preserved where behavior is involved. See the
-[full migration notes](./CHANGELOG.md) before upgrading automated callers.
+v2.7.0 is a runtime-efficiency and error-semantics release: credential-layer
+exceptions are narrowed so real bugs surface, SQLite no longer truncates its WAL
+on every write, and the global connection budget waits on a true async queue
+instead of polling. Public APIs remain backward compatible. See the
+[full migration notes](./CHANGELOG.md).
 
-### Security & Platform
+### Error Semantics
 
-- Minimum supported Python is now **3.10** (3.9 reached EOL on 2025-10-31).
-- Security floors raised: **Paramiko >= 5.0,<6** and **AsyncSSH >= 2.24.0,<3** (2.23.x and earlier are affected by 2026 AsyncSSH advisories).
+- Keyring, encryption, and host-service decrypt paths now catch only expected failure classes; programming errors propagate instead of being silently swallowed.
+- Background pool monitor loops keep their catch-all guard but log full stack traces.
+- Optional `asyncssh` detection uses `find_spec`, so a defect in the async modules themselves can no longer masquerade as "dependency not installed".
 
-### Scalability
+### SQLite WAL Efficiency
 
-- `AsyncBatchExecutor` now uses a **bounded worker queue**: only `min(max_concurrency, host count)` worker tasks are created instead of one task per host, so scheduling memory no longer grows with fleet size.
-- New `OutputPolicy` (exported from `remote_cmd`) gives an explicit, mutually exclusive alternative to `max_output_bytes`; `None` still means full retention in v2.5, and a bounded default is planned for v3.0.
+- `flush()` now runs a **PASSIVE** checkpoint instead of `TRUNCATE` — no more writer waits or WAL rewrites on every host add/update/remove.
+- New explicit `repo.checkpoint("TRUNCATE")` (also `PASSIVE`/`FULL`/`RESTART`) for deliberate WAL compaction.
 
-### Credential Safety
+### Connection Budget
 
-- `JsonHostRepository` / `SqliteHostRepository` accept `allow_plaintext_credentials` (default `None`): plaintext persistence now emits `PlaintextCredentialWarning`; pass `True` to opt in silently or `False` to reject it with `CredentialError`. v3.0 plans to reject by default.
-- JSON repository concurrency semantics are now explicit: single-process/single-writer; use SQLite for multi-process writers.
-- The `dev` extra now includes `asyncssh`, so `pip install -e ".[dev]"` runs the full test suite out of the box.
+- `ConnectionBudget.acquire_async()` now waits on a real queue (`asyncio.Future` woken via `call_soon_threadsafe`), removing the v2.6 polling loop; cancellation-safe and FIFO among async waiters.
 
-### Compatibility
+### Benchmark Data (P2.4)
 
-- `max_output_bytes=None` still retains full output, and the public `BatchResult` / `BatchHostResult` schemas are unchanged; the legacy `max_output_bytes` parameter continues to work alongside `OutputPolicy`.
+- The sync Paramiko path costs ~100 µs per command in thread create/join and peaks at ≈ 3× sustained concurrency in live threads. A centralized channel-reader rewrite is a v2.7.x decision based on these measurements.
 
 ## Table of Contents
 
-- [v2.5.0 Release Highlights](#v250-release-highlights)
+- [v2.7.0 Release Highlights](#v270-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -215,6 +215,7 @@ with SSHClient(config) as client:
 | **Tag System** | Filter hosts by tag (e.g., `production`, `web`, `db`) |
 | **Batch Ops** | Run commands across any host group, synchronously or asynchronously; optional per-host retained-output cap (`max_output_bytes`) |
 | **Async Kernel** | `AsyncSSHClient` / `AsyncConnectionPool` / `AsyncBatchExecutor` via the `[async]` extra |
+| **Global Connection Budget** | Optional `ConnectionBudget` caps live SSH connections process-wide across pools and executors |
 | **Task Runner** | Track and schedule long-running remote tasks with statuses (`TaskRunner`) |
 | **Connection Test** | Test all host SSH connections and report status |
 | **Secure Logging** | Structured logging that filters sensitive data (`SensitiveDataFilter`) |

{remote_cmd_manager-2.5.0 → remote_cmd_manager-2.7.0}/pyproject.toml

@@ -122,6 +122,8 @@ ignore = [
 "__init__.py" = ["E402"]
 # 测试中 pytest fixture 参数未直接引用属于正常模式（如 patch 装饰器触发副作用）
 "tests/test_async_ssh_client.py" = ["ARG002"]
+# mock_paramiko fixture 以 patch 副作用生效，线程模型测试不直接引用其返回值
+"tests/test_ssh_client.py" = ["ARG002"]
 "tests/test_async_batch_executor.py" = ["ARG001", "ARG002"]
 # 连接池测试中 patched_client fixture 触发 patch 副作用，factory 保留 cfg 参数以匹配真实签名
 "tests/test_sync_connection_pool.py" = ["ARG001", "ARG002"]

{remote_cmd_manager-2.5.0 → remote_cmd_manager-2.7.0}/remote_cmd/__init__.py

@@ -48,7 +48,7 @@ Remote CMD - SSH 远程服务器管理工具
     - 文档: 参见 docs/ 目录
 
 Author: Vae-Scrooge
-Version: 2.5.0（单一真相源见 remote_cmd._version）
+Version: 2.7.0（单一真相源见 remote_cmd._version）
 License: MIT
 """
 
@@ -59,23 +59,25 @@ __author__ = "Vae-Scrooge"
 __email__ = "vae-scrooge@example.com"
 __license__ = "MIT"
 
+import importlib.util
 import logging
 
 logging.getLogger(__name__).addHandler(logging.NullHandler())
 
-# 异步原生模块依赖 asyncssh（optional extra [async]），未安装时优雅降级，
-# 避免 `import remote_cmd` 直接失败
-try:
+# 异步原生模块依赖 asyncssh（optional extra [async]）。v2.7（P2.2）起用
+# find_spec 显式探测可选依赖：仅当 asyncssh 缺失时才降级；若 asyncssh 已
+# 安装而我们自己的异步模块 import 失败（代码缺陷/依赖损坏），import
+# 错误会向上传播，不再被静默误判为"未安装 asyncssh"。
+_HAS_ASYNC = importlib.util.find_spec("asyncssh") is not None
+
+if _HAS_ASYNC:
     from remote_cmd.core.async_connection_pool import AsyncConnectionPool
     from remote_cmd.core.async_ssh_client import AsyncSSHClient
     from remote_cmd.service.async_batch_executor import AsyncBatchExecutor
 
-    _HAS_ASYNC = True
-except ImportError:  # pragma: no cover - 依赖 asyncssh，未安装时不导出异步符号
-    _HAS_ASYNC = False
-
+from remote_cmd.api.host_manager import HostManager
+from remote_cmd.core.budget import ConnectionBudget
 from remote_cmd.core.host import Host
-from remote_cmd.core.host_manager import HostManager
 from remote_cmd.core.ssh_client import SSHClient
 from remote_cmd.core.sync_connection_pool import SyncConnectionPool
 
@@ -105,7 +107,7 @@ from remote_cmd.service.batch_executor import (
 from remote_cmd.service.credential_provider import KeyringCredentialProvider
 from remote_cmd.service.task_runner import Task, TaskRunner, TaskStatus
 from remote_cmd.utils.crypto import CredentialEncryption
-from remote_cmd.utils.exceptions import PlaintextCredentialWarning
+from remote_cmd.utils.exceptions import BudgetTimeoutError, PlaintextCredentialWarning
 from remote_cmd.utils.logging_utils import (
     SensitiveDataFilter,
     get_logger,
@@ -142,6 +144,8 @@ if _HAS_ASYNC:
         "BatchHostResult",
         "OutputPolicy",
         "PlaintextCredentialWarning",
+        "ConnectionBudget",
+        "BudgetTimeoutError",
         "SyncConnectionPool",
         "TaskRunner",
         "Task",
@@ -177,6 +181,8 @@ else:
         "BatchHostResult",
         "OutputPolicy",
         "PlaintextCredentialWarning",
+        "ConnectionBudget",
+        "BudgetTimeoutError",
         "SyncConnectionPool",
         "TaskRunner",
         "Task",

{remote_cmd_manager-2.5.0 → remote_cmd_manager-2.7.0}/remote_cmd/_version.py

@@ -9,4 +9,4 @@
 - ``__version__`` 由 ``remote_cmd/__init__.py`` 导入并继续作为公共 API 导出。
 """
 
-__version__ = "2.5.0"
+__version__ = "2.7.0"

remote_cmd_manager-2.7.0/remote_cmd/api/__init__.py

@@ -0,0 +1,22 @@
+"""
+API facade 包（向后兼容层）
+
+存放从 ``core`` 迁出的公共兼容 facade，使核心层（``core``）保持对
+``service`` 的零依赖。当前包含:
+
+    - :class:`remote_cmd.api.host_manager.HostManager`：v1.x 的 HostManager
+      API，内部委托给 HostService + JsonHostRepository。
+
+旧导入路径 ``remote_cmd.core.host_manager`` 仍然可用（re-export shim），
+但新代码应使用 ``remote_cmd.api.host_manager`` 或直接使用 HostService。
+
+依赖方向（v2.6 契约）::
+
+    cli / api → service → core → utils
+    repository ← service / cli
+    core 绝不 import service / cli / api 的实现
+"""
+
+from remote_cmd.api.host_manager import HostManager
+
+__all__ = ["HostManager"]

{remote_cmd_manager-2.5.0/remote_cmd/core → remote_cmd_manager-2.7.0/remote_cmd/api}/host_manager.py

@@ -1,12 +1,18 @@
 """
-主机管理模块（向后兼容层）
+主机管理模块（向后兼容 facade，canonical 位置）
 
-保持原有 API 兼容，内部委托给新的 Repository + Service 层。
+保持原有 HostManager API 兼容，内部委托给新的 Repository + Service 层。
 
 新的代码应直接使用:
     - remote_cmd.core.host.Host (代替 Host)
     - remote_cmd.service.host_service.HostService (代替 HostManager)
     - remote_cmd.repository.json_host_repository.JsonHostRepository
+    - remote_cmd.api.host_manager.HostManager（本模块；仅在需要旧 API 时）
+
+v2.6 架构说明：
+    本模块自 ``remote_cmd.core.host_manager`` 迁至 ``remote_cmd.api``，
+    使 ``core`` 层不再依赖 ``service`` 层。旧导入路径由
+    ``remote_cmd.core.host_manager`` 的 re-export shim 保持可用。
 """
 
 import logging

{remote_cmd_manager-2.5.0 → remote_cmd_manager-2.7.0}/remote_cmd/core/async_connection_pool.py

@@ -19,13 +19,14 @@ import uuid
 from typing import Any, Optional
 
 from remote_cmd.core.async_ssh_client import AsyncSSHClient
-from remote_cmd.core.ssh_client import ConnectionConfig
-from remote_cmd.service._pool_policy import (
+from remote_cmd.core.budget import ConnectionBudget
+from remote_cmd.core.pool_policy import (
     ConnectionMeta,
     idle_expired,
     lifetime_expired,
     should_close,
 )
+from remote_cmd.core.ssh_client import ConnectionConfig
 from remote_cmd.utils.exceptions import PoolClosedError
 
 logger = logging.getLogger(__name__)
@@ -40,6 +41,9 @@ class AsyncConnectionPool:
         max_lifetime: 连接最大生命周期（秒），超过自动关闭
         idle_timeout: 空闲超时（秒），超过自动关闭
         health_check_interval: 后台清理任务周期（秒）
+        connection_budget: 可选的全局连接预算（v2.6）。提供时本池创建的
+            每条存活连接都占用一个预算槽位（含空闲连接），连接关闭/清理/
+            close_all 时释放；跨多个池共享同一预算实例可获得全局连接上限
     """
 
     def __init__(
@@ -50,6 +54,7 @@ class AsyncConnectionPool:
         idle_timeout: int = 300,
         health_check_interval: int = 60,
         client_factory: Optional[Any] = None,
+        connection_budget: Optional[ConnectionBudget] = None,
     ) -> None:
         """
         Args:
@@ -60,6 +65,7 @@ class AsyncConnectionPool:
             health_check_interval: 后台清理任务周期（秒）
             client_factory: 客户端工厂，默认为 AsyncSSHClient；测试可注入
                 mock（与 SyncConnectionPool 对齐）
+            connection_budget: 可选的全局连接预算（ConnectionBudget）
         """
         self.config = config
         self._max = max_connections
@@ -68,6 +74,7 @@ class AsyncConnectionPool:
         self._health_check_interval = health_check_interval
         # 客户端工厂：默认为 AsyncSSHClient；测试可注入 mock
         self._client_factory = client_factory or AsyncSSHClient
+        self._connection_budget = connection_budget
 
         # 容器
         self._connections: list[AsyncSSHClient] = []
@@ -190,10 +197,16 @@ class AsyncConnectionPool:
     # ------------------------------------------------------------------
     async def _create_connection(self) -> AsyncSSHClient:
         client = self._client_factory(self.config)
+        if self._connection_budget is not None:
+            await self._connection_budget.acquire_async()
         try:
             await client.connect()
         except Exception:  # noqa: BLE001
-            # 信号量由 acquire() 的 except 统一释放，此处不再释放
+            # 信号量由 acquire() 的 except 统一释放，此处不再释放。
+            # 连接预算仅在成功建连后由 _close_connection 释放；
+            # 建连失败立即归还预算，避免预算泄漏
+            if self._connection_budget is not None:
+                await self._connection_budget.release_async()
             self._total_failed += 1
             raise
         self._connections.append(client)
@@ -237,8 +250,14 @@ class AsyncConnectionPool:
         with contextlib.suppress(Exception):
             await conn.disconnect()
         self._meta.pop(id(conn), None)
-        if conn in self._connections:
+        tracked = conn in self._connections
+        if tracked:
             self._connections.remove(conn)
+        # exactly-once：仅对仍被池追踪的连接释放预算。
+        # close_all 与 release 可能对同一连接重复调用 _close_connection，
+        # 用 tracked 守卫避免预算被超额释放（BoundedSemaphore 会抛 ValueError）
+        if tracked and self._connection_budget is not None:
+            await self._connection_budget.release_async()
 
     # ------------------------------------------------------------------
     # 后台监控
@@ -259,7 +278,9 @@ class AsyncConnectionPool:
             except asyncio.CancelledError:
                 break
             except Exception:  # noqa: BLE001
-                logger.warning("connection pool monitor error")
+                # 后台清理任务必须吞掉一切非取消异常以保持存活（单次清理
+                # 失败不应终止后续周期）；保留完整堆栈便于定位
+                logger.warning("connection pool monitor error", exc_info=True)
 
     async def _cleanup_expired(self) -> None:
         now = time.time()

remote_cmd_manager-2.7.0/remote_cmd/core/budget.py

@@ -0,0 +1,283 @@
+"""
+全局连接预算（v2.6 P2.5；v2.7 真异步等待队列）
+
+用于在**多个连接池 / 多个执行器**之间封顶进程内同时存活的 SSH 连接数，
+避免大规模 fleet 场景下 per-pool 上限叠加导致的 fd/socket 耗尽：
+
+    池 A(max=10) + 池 B(max=10) + …   无预算时可无限叠加
+    预算(max=50)                       全局硬上限 50 条存活连接
+
+预算语义（存活连接预算）：
+- 预算单位 = **存活连接**（含池中空闲连接）。
+- 获取时机：连接创建（``connect``）前；释放时机：连接断开 / 关闭 /
+  被清理 / 池 ``close_all``。
+- 池归还空闲连接**不**释放预算（连接仍存活）；``acquire`` 复用空闲连接
+  **不**重复获取预算。
+
+双接口：
+- 同步：:meth:`acquire` / :meth:`release` / :meth:`acquire_context`
+- 异步：:meth:`acquire_async` / :meth:`release_async` /
+  :meth:`acquire_context_async`
+
+同一实例可被同步与异步执行器共享：容量与等待队列由单个
+``threading.Condition`` 保护；异步等待者注册 ``asyncio.Future``，
+释放时通过 ``loop.call_soon_threadsafe`` 精准唤醒（v2.7 P2.5 优化：
+取代 v2.6 的 10→50ms 轮询，无空转 wakeup）。
+
+唤醒语义（condition-variable 模式）：
+- 唤醒只是"提示"而非预留：被唤醒者需重新竞争容量；释放方不预占槽位。
+- 异步等待者之间 FIFO；同步等待者之间 FIFO；跨类型顺序不作保证。
+- 等待者超时/取消时会从队列移除；若唤醒权已派发给它，
+  ``_resolve_waiter`` 检测到 future 已完成会补唤醒下一个等待者，
+  不会因取消竞态丢失唤醒。
+
+超时：``acquire_timeout=None``（默认）无限等待；配置正整数/浮点秒数时
+超时抛出 :class:`~remote_cmd.utils.exceptions.BudgetTimeoutError`。
+
+用法:
+    >>> from remote_cmd.core.budget import ConnectionBudget
+    >>> budget = ConnectionBudget(max_connections=50)
+    >>> with budget.acquire_context():
+    ...     pass  # 持有预算期间创建/保有连接
+    >>> budget.get_metrics()["in_use"]
+    0
+    >>>
+    >>> async def use():
+    ...     async with budget.acquire_context_async():
+    ...         pass
+"""
+
+import asyncio
+import contextlib
+import threading
+import time
+from collections import deque
+from typing import Any, AsyncIterator, Deque, Iterator, Optional
+
+from remote_cmd.utils.exceptions import BudgetTimeoutError, ValidationError
+
+
+class ConnectionBudget:
+    """全局连接预算（同步 / 异步共用）。
+
+    Args:
+        max_connections: 全局最大存活连接数（正整数；bool 被拒绝）
+        acquire_timeout: 获取预算的等待上限（秒）。``None``（默认）
+            表示无限等待；正数表示超时后抛 ``BudgetTimeoutError``
+
+    Raises:
+        ValidationError: 参数非法（构造时校验）
+    """
+
+    def __init__(
+        self,
+        max_connections: int,
+        acquire_timeout: Optional[float] = None,
+    ) -> None:
+        if (
+            isinstance(max_connections, bool)
+            or not isinstance(max_connections, int)
+            or max_connections <= 0
+        ):
+            raise ValidationError(
+                f"max_connections must be a positive integer, got: {max_connections!r}"
+            )
+        if acquire_timeout is not None and (
+            isinstance(acquire_timeout, bool)
+            or not isinstance(acquire_timeout, (int, float))
+            or acquire_timeout <= 0
+        ):
+            raise ValidationError(
+                f"acquire_timeout must be None or a positive number, got: {acquire_timeout!r}"
+            )
+
+        self._max = max_connections
+        self._acquire_timeout = acquire_timeout
+
+        # 单一互斥 + 条件变量：保护容量计数与等待队列（同步/异步共享）
+        self._cond = threading.Condition(threading.Lock())
+        self._in_use = 0
+        self._async_waiters: Deque[asyncio.Future[None]] = deque()
+
+        # 指标
+        self._total_acquired = 0
+        self._total_released = 0
+        self._total_timeouts = 0
+
+    # ------------------------------------------------------------------
+    # 属性 / 指标
+    # ------------------------------------------------------------------
+    @property
+    def max_connections(self) -> int:
+        """全局最大存活连接数。"""
+        return self._max
+
+    @property
+    def acquire_timeout(self) -> Optional[float]:
+        """获取预算的等待上限（秒）；``None`` 表示无限等待。"""
+        return self._acquire_timeout
+
+    def get_metrics(self) -> dict[str, Any]:
+        """预算指标快照。"""
+        with self._cond:
+            return {
+                "max_connections": self._max,
+                "in_use": self._in_use,
+                "available": self._max - self._in_use,
+                "total_acquired": self._total_acquired,
+                "total_released": self._total_released,
+                "total_timeouts": self._total_timeouts,
+            }
+
+    # ------------------------------------------------------------------
+    # 同步接口
+    # ------------------------------------------------------------------
+    def acquire(self) -> None:
+        """获取一个连接预算槽位（阻塞，受 ``acquire_timeout`` 约束）。
+
+        Raises:
+            BudgetTimeoutError: 等待超过 ``acquire_timeout``
+        """
+        timeout = self._acquire_timeout
+        deadline = None if timeout is None else time.monotonic() + timeout
+        with self._cond:
+            while self._in_use >= self._max:
+                remaining = None if deadline is None else deadline - time.monotonic()
+                if remaining is not None and remaining <= 0:
+                    self._total_timeouts += 1
+                    # 超时者退出前让出一次唤醒权，避免其他同步等待者
+                    # 因槽位空闲却无人被通知而饥饿
+                    self._cond.notify()
+                    raise BudgetTimeoutError(
+                        "connection budget exhausted: "
+                        f"waited {timeout}s for a slot "
+                        f"(max_connections={self._max})"
+                    )
+                self._cond.wait(remaining)
+            self._in_use += 1
+            self._total_acquired += 1
+
+    def release(self) -> None:
+        """释放一个连接预算槽位并唤醒一个等待者。
+
+        Raises:
+            ValueError: 释放次数超过获取次数
+        """
+        with self._cond:
+            if self._in_use <= 0:
+                raise ValueError("release without a matching acquire")
+            self._in_use -= 1
+            self._total_released += 1
+            self._wake_next_locked()
+
+    @contextlib.contextmanager
+    def acquire_context(self) -> Iterator[None]:
+        """同步上下文管理器：进入获取预算，退出释放。"""
+        self.acquire()
+        try:
+            yield
+        finally:
+            self.release()
+
+    # ------------------------------------------------------------------
+    # 异步接口
+    # ------------------------------------------------------------------
+    async def acquire_async(self) -> None:
+        """获取一个连接预算槽位（asyncio 原生等待，受 ``acquire_timeout`` 约束）。
+
+        通过注册 ``asyncio.Future`` 等待释放方唤醒，不使用轮询。
+        """
+        timeout = self._acquire_timeout
+        deadline = None if timeout is None else time.monotonic() + timeout
+        loop = asyncio.get_running_loop()
+        while True:
+            with self._cond:
+                if self._in_use < self._max:
+                    self._in_use += 1
+                    self._total_acquired += 1
+                    return
+                remaining = None if deadline is None else deadline - time.monotonic()
+                if remaining is not None and remaining <= 0:
+                    self._total_timeouts += 1
+                    self._cond.notify()
+                    raise BudgetTimeoutError(
+                        "connection budget exhausted: "
+                        f"waited {timeout}s for a slot "
+                        f"(max_connections={self._max})"
+                    )
+                fut: asyncio.Future[None] = loop.create_future()
+                self._async_waiters.append(fut)
+            try:
+                if remaining is None:
+                    await fut
+                else:
+                    await asyncio.wait_for(fut, remaining)
+            except asyncio.TimeoutError:
+                with self._cond:
+                    self._discard_waiter_locked(fut)
+                    self._total_timeouts += 1
+                    # 若唤醒权已被派发给本 future（弹出后 resolve 前超时），
+                    # _resolve_waiter 会发现 fut 已完成并补唤醒下一个等待者
+                raise BudgetTimeoutError(
+                    "connection budget exhausted: "
+                    f"waited {timeout}s for a slot "
+                    f"(max_connections={self._max})"
+                ) from None
+            except asyncio.CancelledError:
+                with self._cond:
+                    self._discard_waiter_locked(fut)
+                raise
+            # 被唤醒后回到循环顶部重新竞争容量（唤醒不预留槽位）
+
+    async def release_async(self) -> None:
+        """释放一个连接预算槽位（异步接口；与 :meth:`release` 等价）。"""
+        self.release()
+
+    @contextlib.asynccontextmanager
+    async def acquire_context_async(self) -> AsyncIterator[None]:
+        """异步上下文管理器：进入获取预算，退出释放。"""
+        await self.acquire_async()
+        try:
+            yield
+        finally:
+            await self.release_async()
+
+    # ------------------------------------------------------------------
+    # 内部：等待队列
+    # ------------------------------------------------------------------
+    def _discard_waiter_locked(self, fut: asyncio.Future[None]) -> None:
+        """从异步等待队列移除 future（不存在则忽略）。须持锁调用。"""
+        with contextlib.suppress(ValueError):
+            self._async_waiters.remove(fut)
+
+    def _wake_next_locked(self) -> None:
+        """唤醒一个等待者（异步优先 FIFO，否则通知一个同步等待者）。
+
+        唤醒不预留槽位；被唤醒者会重新检查容量。须持锁调用。
+        """
+        while self._async_waiters:
+            fut = self._async_waiters.popleft()
+            if fut.done():
+                continue
+            loop = fut.get_loop()
+            if loop.is_closed():
+                continue
+            try:
+                loop.call_soon_threadsafe(self._resolve_waiter, fut)
+            except RuntimeError:
+                # 事件循环正在关闭：跳过该等待者，尝试下一个
+                continue
+            return
+        self._cond.notify()
+
+    def _resolve_waiter(self, fut: asyncio.Future[None]) -> None:
+        """在事件循环线程内完成 future（或补唤醒下一个等待者）。"""
+        if fut.done():
+            # 等待者已超时/取消：唤醒权未被消费，补唤醒下一个
+            with self._cond:
+                self._wake_next_locked()
+            return
+        fut.set_result(None)
+
+
+__all__ = ["ConnectionBudget"]