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

{remote_cmd_manager-2.6.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.6.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,32 +89,36 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.6.0 Release Highlights
+## v2.7.0 Release Highlights
 
-v2.6.0 is an architecture and runtime-scalability release: the compatibility facade
-moved out of `core` (eliminating the `core → service` dependency) and a process-wide
-live-connection budget was added for fleet-scale resource control. Public APIs remain
-backward compatible. See the [full migration notes](./CHANGELOG.md).
+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).
 
-### Architecture
+### Error Semantics
 
-- `HostManager` now lives in `remote_cmd.api.host_manager`; `remote_cmd.core.host_manager` remains a re-export shim, so existing imports keep working.
-- Pool policy helpers moved to `remote_cmd.core.pool_policy` (shim kept at the old path); `core` no longer imports `service`.
-- The async kernel's worker queue now converts unexpected per-host errors into failure results, so a single internal error can no longer stall an entire batch.
+- 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".
 
-### Global Connection Budget
+### SQLite WAL Efficiency
 
-- New `ConnectionBudget` (exported from `remote_cmd`): caps **live** SSH connections process-wide across pools and executors — idle pooled connections count, and slots release on close/cleanup/`close_all`.
-- One instance can be shared by both kernels via `connection_budget=` on `BatchExecutor`, `AsyncBatchExecutor`, `SyncConnectionPool`, and `AsyncConnectionPool`.
-- Optional `acquire_timeout` raises the transient `BudgetTimeoutError`; the default (`None`) keeps unlimited behavior.
+- `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.
 
-### Compatibility
+### Connection Budget
 
-- All existing imports and constructor signatures keep working; new parameters are optional and default to previous behavior.
+- `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.
+
+### Benchmark Data (P2.4)
+
+- 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.6.0 Release Highlights](#v260-release-highlights)
+- [v2.7.0 Release Highlights](#v270-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)

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

@@ -36,32 +36,36 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.6.0 Release Highlights
+## v2.7.0 Release Highlights
 
-v2.6.0 is an architecture and runtime-scalability release: the compatibility facade
-moved out of `core` (eliminating the `core → service` dependency) and a process-wide
-live-connection budget was added for fleet-scale resource control. Public APIs remain
-backward compatible. See the [full migration notes](./CHANGELOG.md).
+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).
 
-### Architecture
+### Error Semantics
 
-- `HostManager` now lives in `remote_cmd.api.host_manager`; `remote_cmd.core.host_manager` remains a re-export shim, so existing imports keep working.
-- Pool policy helpers moved to `remote_cmd.core.pool_policy` (shim kept at the old path); `core` no longer imports `service`.
-- The async kernel's worker queue now converts unexpected per-host errors into failure results, so a single internal error can no longer stall an entire batch.
+- 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".
 
-### Global Connection Budget
+### SQLite WAL Efficiency
 
-- New `ConnectionBudget` (exported from `remote_cmd`): caps **live** SSH connections process-wide across pools and executors — idle pooled connections count, and slots release on close/cleanup/`close_all`.
-- One instance can be shared by both kernels via `connection_budget=` on `BatchExecutor`, `AsyncBatchExecutor`, `SyncConnectionPool`, and `AsyncConnectionPool`.
-- Optional `acquire_timeout` raises the transient `BudgetTimeoutError`; the default (`None`) keeps unlimited behavior.
+- `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.
 
-### Compatibility
+### Connection Budget
 
-- All existing imports and constructor signatures keep working; new parameters are optional and default to previous behavior.
+- `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.
+
+### Benchmark Data (P2.4)
+
+- 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.6.0 Release Highlights](#v260-release-highlights)
+- [v2.7.0 Release Highlights](#v270-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)

{remote_cmd_manager-2.6.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.6.0 → remote_cmd_manager-2.7.0}/remote_cmd/__init__.py

@@ -48,7 +48,7 @@ Remote CMD - SSH 远程服务器管理工具
     - 文档: 参见 docs/ 目录
 
 Author: Vae-Scrooge
-Version: 2.6.0（单一真相源见 remote_cmd._version）
+Version: 2.7.0（单一真相源见 remote_cmd._version）
 License: MIT
 """
 
@@ -59,21 +59,22 @@ __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

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

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

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

@@ -278,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.6.0 → remote_cmd_manager-2.7.0}/remote_cmd/core/budget.py

@@ -1,5 +1,5 @@
 """
-全局连接预算（v2.6 P2.5；同步 / 异步内核共用）
+全局连接预算（v2.6 P2.5；v2.7 真异步等待队列）
 
 用于在**多个连接池 / 多个执行器**之间封顶进程内同时存活的 SSH 连接数，
 避免大规模 fleet 场景下 per-pool 上限叠加导致的 fd/socket 耗尽：
@@ -7,7 +7,7 @@
     池 A(max=10) + 池 B(max=10) + …   无预算时可无限叠加
     预算(max=50)                       全局硬上限 50 条存活连接
 
-预算语义（评审定稿：存活连接预算）：
+预算语义（存活连接预算）：
 - 预算单位 = **存活连接**（含池中空闲连接）。
 - 获取时机：连接创建（``connect``）前；释放时机：连接断开 / 关闭 /
   被清理 / 池 ``close_all``。
@@ -19,10 +19,17 @@
 - 异步：:meth:`acquire_async` / :meth:`release_async` /
   :meth:`acquire_context_async`
 
-同一实例可被同步与异步执行器共享（底层是单个
-``threading.BoundedSemaphore``；异步侧以非阻塞轮询等待，轮询间隔
-10ms 起步、指数退避至 50ms——相对于 SSH 建连耗时（数十到数百 ms）
-开销可忽略）。
+同一实例可被同步与异步执行器共享：容量与等待队列由单个
+``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`。
@@ -44,14 +51,11 @@ import asyncio
 import contextlib
 import threading
 import time
-from typing import Any, AsyncIterator, Iterator, Optional
+from collections import deque
+from typing import Any, AsyncIterator, Deque, Iterator, Optional
 
 from remote_cmd.utils.exceptions import BudgetTimeoutError, ValidationError
 
-# 异步轮询等待参数（秒）：起步 10ms，指数退避至 50ms 上限
-_DEFAULT_POLL_INTERVAL = 0.01
-_MAX_POLL_INTERVAL = 0.05
-
 
 class ConnectionBudget:
     """全局连接预算（同步 / 异步共用）。
@@ -89,12 +93,13 @@ class ConnectionBudget:
 
         self._max = max_connections
         self._acquire_timeout = acquire_timeout
-        # 单一底层信号量：同步/异步共享同一个全局上限
-        self._semaphore = threading.BoundedSemaphore(max_connections)
-        self._lock = threading.Lock()
 
-        # 指标
+        # 单一互斥 + 条件变量：保护容量计数与等待队列（同步/异步共享）
+        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
@@ -114,7 +119,7 @@ class ConnectionBudget:
 
     def get_metrics(self) -> dict[str, Any]:
         """预算指标快照。"""
-        with self._lock:
+        with self._cond:
             return {
                 "max_connections": self._max,
                 "in_use": self._in_use,
@@ -133,31 +138,37 @@ class ConnectionBudget:
         Raises:
             BudgetTimeoutError: 等待超过 ``acquire_timeout``
         """
-        acquired = self._semaphore.acquire(timeout=self._acquire_timeout)
-        if not acquired:
-            with self._lock:
-                self._total_timeouts += 1
-            raise BudgetTimeoutError(
-                "connection budget exhausted: "
-                f"waited {self._acquire_timeout}s for a slot "
-                f"(max_connections={self._max})"
-            )
-        with self._lock:
+        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: 释放次数超过获取次数（BoundedSemaphore 保护）
+            ValueError: 释放次数超过获取次数
         """
-        # 先释放信号量：超额释放时 BoundedSemaphore 抛出 ValueError，
-        # 指标不会进入不一致状态
-        self._semaphore.release()
-        with self._lock:
+        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]:
@@ -172,27 +183,51 @@ class ConnectionBudget:
     # 异步接口
     # ------------------------------------------------------------------
     async def acquire_async(self) -> None:
-        """获取一个连接预算槽位（asyncio 友好，受 ``acquire_timeout`` 约束）。
+        """获取一个连接预算槽位（asyncio 原生等待，受 ``acquire_timeout`` 约束）。
 
-        以非阻塞尝试 + 指数退避轮询等待，不阻塞事件循环。
+        通过注册 ``asyncio.Future`` 等待释放方唤醒，不使用轮询。
         """
         timeout = self._acquire_timeout
         deadline = None if timeout is None else time.monotonic() + timeout
-        interval = _DEFAULT_POLL_INTERVAL
-        while not self._semaphore.acquire(blocking=False):
-            if deadline is not None and time.monotonic() >= deadline:
-                with self._lock:
+        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})"
-                )
-            await asyncio.sleep(interval)
-            interval = min(interval * 2, _MAX_POLL_INTERVAL)
-        with self._lock:
-            self._in_use += 1
-            self._total_acquired += 1
+                ) from None
+            except asyncio.CancelledError:
+                with self._cond:
+                    self._discard_waiter_locked(fut)
+                raise
+            # 被唤醒后回到循环顶部重新竞争容量（唤醒不预留槽位）
 
     async def release_async(self) -> None:
         """释放一个连接预算槽位（异步接口；与 :meth:`release` 等价）。"""
@@ -207,5 +242,42 @@ class ConnectionBudget:
         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"]

{remote_cmd_manager-2.6.0 → remote_cmd_manager-2.7.0}/remote_cmd/core/sync_connection_pool.py

@@ -279,7 +279,9 @@ class SyncConnectionPool:
                     break
                 self._cleanup_expired()
             except Exception:  # noqa: BLE001
-                logger.warning("connection pool monitor error")
+                # 后台清理线程必须吞掉一切异常以保持存活（守护线程；
+                # 单次清理失败不应终止后续周期）；保留完整堆栈便于定位
+                logger.warning("connection pool monitor error", exc_info=True)
 
     def _cleanup_expired(self) -> None:
         now = time.time()

{remote_cmd_manager-2.6.0 → remote_cmd_manager-2.7.0}/remote_cmd/repository/sqlite_host_repository.py

@@ -29,7 +29,11 @@ from remote_cmd.core.host import Host
 from remote_cmd.repository.host_repository import HostRepository
 from remote_cmd.utils.credential_guard import PasswordGuard, is_plaintext_password
 from remote_cmd.utils.crypto import CredentialEncryption
-from remote_cmd.utils.exceptions import CredentialError, PlaintextCredentialWarning
+from remote_cmd.utils.exceptions import (
+    CredentialError,
+    PlaintextCredentialWarning,
+    ValidationError,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -70,6 +74,9 @@ CREATE TABLE IF NOT EXISTS meta (
 # 写锁等待上限（毫秒）：多进程并发写同一数据库时，等待对方短事务提交/回滚
 DEFAULT_BUSY_TIMEOUT_MS = 5000
 
+# 显式 checkpoint 允许的模式白名单（防 SQL 注入；SQLite wal_checkpoint 模式）
+CHECKPOINT_MODES = frozenset({"PASSIVE", "FULL", "RESTART", "TRUNCATE"})
+
 
 class SqliteHostRepository(HostRepository):
     """
@@ -384,12 +391,41 @@ class SqliteHostRepository(HostRepository):
         return row["cnt"] if row else 0
 
     def flush(self) -> None:
+        """轻量刷新：执行一次 PASSIVE WAL checkpoint（v2.7 P2.3）。
+
+        SQLite 写入即时生效，本方法是与 JsonHostRepository 对齐的接口。
+
+        v2.7 起不再在每次 flush 执行 ``wal_checkpoint(TRUNCATE)``：
+        HostService 的 add/update/remove 每次都会调用 flush，TRUNCATE 会
+        等待所有读者并在 checkpoint 后截断 WAL 文件，造成写放大与读阻塞
+        风险。PASSIVE 不等待、不截断，仅将可安全写回的帧写回数据库；
+        WAL 增长由 SQLite 自动 checkpoint（默认 1000 页）控制。
+        需要主动压缩 WAL 时请调用 :meth:`checkpoint`。
         """
-        SQLite 写入即时生效，flush 为空操作
-        此处仅触发一个检查点以压缩 WAL 日志
+        with self._lock, self._txn() as conn:
+            conn.execute("PRAGMA wal_checkpoint(PASSIVE);")
+
+    def checkpoint(self, mode: str = "TRUNCATE") -> None:
+        """执行显式 WAL checkpoint（v2.7 P2.3），用于按需压缩 WAL 文件。
+
+        Args:
+            mode: checkpoint 模式（大小写不敏感）：
+                - ``PASSIVE``：不等待读者、不截断（与 flush 相同）
+                - ``FULL``：等待所有读者完成
+                - ``RESTART``：等待读者完成后重启 WAL 日志
+                - ``TRUNCATE``（默认）：等待读者完成后截断 WAL 文件
+
+        Raises:
+            ValidationError: mode 不在白名单内（防 SQL 注入）
         """
+        normalized = mode.strip().upper()
+        if normalized not in CHECKPOINT_MODES:
+            raise ValidationError(
+                f"unsupported checkpoint mode: {mode!r} "
+                f"(expected one of: {', '.join(sorted(CHECKPOINT_MODES))})"
+            )
         with self._lock, self._txn() as conn:
-            conn.execute("PRAGMA wal_checkpoint(TRUNCATE);")
+            conn.execute(f"PRAGMA wal_checkpoint({normalized});")
 
     # ========================================================================
     # 扩展方法（非 ABC 接口）

{remote_cmd_manager-2.6.0 → remote_cmd_manager-2.7.0}/remote_cmd/service/credential_provider.py

@@ -32,6 +32,23 @@ from remote_cmd.utils.crypto import CredentialEncryption
 logger = logging.getLogger(__name__)
 
 
+def _keyring_backend_errors() -> tuple[type[BaseException], ...]:
+    """keyring 后端不可用/存取失败的异常集合（v2.7 P2.2）。
+
+    惰性导入（keyring 为可选依赖），仅覆盖**后端类**失败：
+
+    - ``keyring.errors.KeyringError`` 及其子类（NoKeyringError / KeyringLocked 等）
+    - ``OSError``：后端 I/O 失败（文件后端 / D-Bus 等）
+    - ``RuntimeError``：部分后端无可用实现时抛出的运行态错误
+
+    编程错误（TypeError / AttributeError 等）不再被吞掉，会向上传播，
+    避免把代码缺陷伪装成"keyring 不可用"。
+    """
+    from keyring import errors as keyring_errors
+
+    return (keyring_errors.KeyringError, OSError, RuntimeError)
+
+
 class CredentialProvider(ABC):
     """凭据提供者抽象基类"""
 
@@ -177,7 +194,7 @@ class KeyringCredentialProvider(CredentialProvider):
         except ImportError:
             logger.debug("keyring not installed, skipping KeyringCredentialProvider")
             return None
-        except Exception as e:  # noqa: BLE001
+        except _keyring_backend_errors() as e:
             logger.debug(f"keyring access failed: {e}")
             return None
 
@@ -197,7 +214,10 @@ class KeyringCredentialProvider(CredentialProvider):
 
             keyring.set_password(self._service_name, host.name, password)
             return True
-        except Exception as e:  # noqa: BLE001
+        except ImportError:
+            logger.debug("keyring not installed, cannot store password")
+            return False
+        except _keyring_backend_errors() as e:
             logger.debug(f"keyring store failed: {e}")
             return False
 
@@ -216,6 +236,9 @@ class KeyringCredentialProvider(CredentialProvider):
 
             keyring.delete_password(self._service_name, host.name)
             return True
-        except Exception as e:  # noqa: BLE001
+        except ImportError:
+            logger.debug("keyring not installed, cannot delete password")
+            return False
+        except _keyring_backend_errors() as e:
             logger.debug(f"keyring delete failed: {e}")
             return False

{remote_cmd_manager-2.6.0 → remote_cmd_manager-2.7.0}/remote_cmd/service/host_service.py

@@ -37,7 +37,7 @@ from remote_cmd.service.credential_provider import (
     EnvCredentialProvider,
 )
 from remote_cmd.service.ssh_service import SSHService
-from remote_cmd.utils.crypto import CredentialEncryption
+from remote_cmd.utils.crypto import CredentialEncryption, CredentialEncryptionError
 
 logger = logging.getLogger(__name__)
 
@@ -245,7 +245,7 @@ class HostService:
             try:
                 decrypted = self._encryption.decrypt(host.password)
                 return self._build_resolved_host(host, decrypted, host.key_filename)
-            except Exception as e:  # noqa: BLE001
+            except CredentialEncryptionError as e:
                 # 解密失败不应阻塞整批主机返回：保留加密 token，
                 # 让 SSH 层在真正连接时报告认证失败
                 logger.warning(f"failed to decrypt password for {host.name}: {e}")
@@ -281,7 +281,7 @@ class HostService:
                 # 凭据链未命中，回退到本地加密器解密
                 try:
                     resolved_password = self._encryption.decrypt(host.password)
-                except Exception as e:  # noqa: BLE001
+                except CredentialEncryptionError as e:
                     logger.warning(f"failed to decrypt password for {host.name}: {e}")
                     # 保留加密 token，留给 SSH 层报认证失败
 

{remote_cmd_manager-2.6.0 → remote_cmd_manager-2.7.0}/remote_cmd/utils/crypto.py

@@ -91,7 +91,7 @@ class CredentialEncryption:
         try:
             token = self._cipher.encrypt(plaintext.encode("utf-8"))
             return self._PREFIX + token.decode("utf-8")
-        except Exception as e:
+        except (TypeError, ValueError) as e:
             raise CredentialEncryptionError(f"encryption failed: {e}") from e
 
     def decrypt(self, ciphertext: str) -> str:
@@ -110,10 +110,15 @@ class CredentialEncryption:
         if not ciphertext.startswith(self._PREFIX):
             raise CredentialEncryptionError("invalid ciphertext format")
 
+        from cryptography.fernet import InvalidToken
+
         try:
             token = ciphertext[len(self._PREFIX) :].encode("utf-8")
             return self._cipher.decrypt(token).decode("utf-8")
-        except Exception as e:
+        # InvalidToken：签名/内容损坏；ValueError（含 binascii.Error）：
+        # base64/格式非法；TypeError：token 类型错误。其余异常（如密钥加载
+        # 缺陷或 cryptography 内部错误）向上传播，不再伪装为"解密失败"。
+        except (InvalidToken, ValueError, TypeError) as e:
             raise CredentialEncryptionError(f"decryption failed: {e}") from e
 
     def is_encrypted(self, value: str) -> bool: