Route release/drain close sites through _close_best_effort with DEBUG log

The seven release/drain close sites used
`contextlib.suppress(*_POOL_CLEANUP_EXCEPTIONS)` to absorb a half-
torn-down transport's `OSError` / `DqliteConnectionError` /
`ProtocolError` / `OperationalError` / `InterfaceError` from
`conn.close()` — but `contextlib.suppress` has no logging surface, so
the suppressed exception left no trace at any verbosity. The sibling
`_initialize_close_unqueued` used `try/except` + `logger.debug(...,
exc_info=True)`; the asymmetry was a residual diagnostic gap after the
prior `_POOL_CLEANUP_EXCEPTIONS` narrowing pass.

Extract `_close_best_effort(conn, site)` matching the initialize-
helper shape (shielded close + DEBUG log with `exc_info=True`) and
route all seven sites through it. Each site passes a stable identifier
so operators can locate the emitting branch in `pool.<site>: close
error` log records.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: antoineleclair

src/dqliteclient/pool.py

@@ -1000,6 +1000,40 @@ async def _initialize_close_unqueued(
                     exc_info=True,
                 )
 
+    async def _close_best_effort(self, conn: DqliteConnection, site: str) -> None:
+        """Best-effort shielded close that logs ``_POOL_CLEANUP_EXCEPTIONS``
+        at DEBUG with ``exc_info=True`` rather than silently swallowing
+        them.
+
+        ``site`` is a short identifier appended to the log key
+        (``"pool.<site>: close error"``) so operators can locate which
+        call site emitted the record. Mirrors the
+        ``_initialize_close_unqueued`` discipline — both helpers now log
+        through ``exc_info=True`` so the suppressed-exception chain is
+        recoverable at DEBUG verbosity instead of being silently
+        dropped by ``contextlib.suppress`` (which has no logging
+        surface). The asymmetry between the initialize-time helper
+        (logged) and the release-time sites (silent) was a residual
+        diagnostic gap after the prior ``_POOL_CLEANUP_EXCEPTIONS``
+        narrowing pass; routing all release/drain close sites through
+        this helper closes it.
+
+        Cancel-safety: ``asyncio.shield`` runs the close to completion
+        even if an outer cancel is delivered during the await; the
+        CancelledError still propagates to the caller after the close
+        finishes. The CancelledError arm is intentionally NOT caught
+        here — preserves the pre-existing behaviour of the sites this
+        helper replaces (``contextlib.suppress(*_POOL_CLEANUP_EXCEPTIONS)``
+        suppressed only the cleanup-exception tuple; CancelledError
+        propagated to the surrounding frame). Sites that need to keep
+        running through cancel (like ``_initialize_close_unqueued``'s
+        per-conn walk) handle that arm explicitly.
+        """
+        try:
+            await asyncio.shield(conn.close())
+        except _POOL_CLEANUP_EXCEPTIONS:
+            logger.debug("pool.%s: close error", site, exc_info=True)
+
     async def _create_connection(self) -> DqliteConnection:
         """Create a new connection to the leader.
 
@@ -1060,20 +1094,22 @@ async def _put_back_or_release_late_winner(self, conn: DqliteConnection) -> None
             # had happened. Mirrors the ``_drain_idle`` discipline.
             conn._pool_released = False
             try:
-                # Suppress the canonical ``_POOL_CLEANUP_EXCEPTIONS``
-                # tuple (OSError + DqliteConnectionError + ProtocolError
-                # + OperationalError + InterfaceError), not just
-                # ``OSError``. A late-winner conn whose transport was
-                # broken by a peer reset between checkout and close
-                # raises one of the broader categories from
-                # ``close()``; pre-fix that exception escaped, the
+                # Route through ``_close_best_effort`` so the canonical
+                # ``_POOL_CLEANUP_EXCEPTIONS`` tuple (OSError +
+                # DqliteConnectionError + ProtocolError +
+                # OperationalError + InterfaceError) is absorbed at
+                # DEBUG with ``exc_info=True`` (matches the sibling
+                # ``_initialize_close_unqueued`` discipline) rather
+                # than silently dropped. A late-winner conn whose
+                # transport was broken by a peer reset between
+                # checkout and close raises one of the broader
+                # categories from ``close()``; the helper logs them
+                # and proceeds so ``_release_reservation`` still runs
+                # below — pre-fix-narrow those exceptions escaped, the
                 # ``finally`` restored the flag, and
-                # ``_release_reservation`` was NEVER reached — the
-                # reservation slot leaked permanently. Matches the
-                # canonical ``_release`` discipline at the sibling
-                # close-and-track path.
-                with contextlib.suppress(*_POOL_CLEANUP_EXCEPTIONS):
-                    await asyncio.shield(conn.close())
+                # ``_release_reservation`` was NEVER reached, leaking
+                # the reservation slot permanently.
+                await self._close_best_effort(conn, "acquire-late-winner-closed")
             finally:
                 # Restore the flag for contract symmetry with
                 # ``_drain_idle``: any stale-reference second close()
@@ -1092,18 +1128,19 @@ async def _put_back_or_release_late_winner(self, conn: DqliteConnection) -> None
             # the reference would leak a live reader task and a
             # socket. Close explicitly and adjust the reservation
             # count so the pool shrinks cleanly instead of leaking.
-            # Suppress the canonical ``_POOL_CLEANUP_EXCEPTIONS``
-            # tuple — a half-torn-down transport raises
-            # ``DqliteConnectionError`` / ``InterfaceError`` /
-            # ``ProtocolError`` / ``OperationalError`` in addition to
-            # plain ``OSError``; pre-fix the broader categories
-            # escaped and the slot leaked. Flip ``_pool_released``
-            # to ``False`` first so the close actually runs (see
-            # the closed-pool arm above for the rationale).
+            # Route through ``_close_best_effort`` so the canonical
+            # ``_POOL_CLEANUP_EXCEPTIONS`` tuple — a half-torn-down
+            # transport raises ``DqliteConnectionError`` /
+            # ``InterfaceError`` / ``ProtocolError`` /
+            # ``OperationalError`` in addition to plain ``OSError`` —
+            # is absorbed at DEBUG with ``exc_info=True``; pre-fix-
+            # narrow the broader categories escaped and the slot
+            # leaked. Flip ``_pool_released`` to ``False`` first so
+            # the close actually runs (see the closed-pool arm above
+            # for the rationale).
             conn._pool_released = False
             try:
-                with contextlib.suppress(*_POOL_CLEANUP_EXCEPTIONS):
-                    await asyncio.shield(conn.close())
+                await self._close_best_effort(conn, "acquire-late-winner-queuefull")
             finally:
                 conn._pool_released = True
             # Route through the helper so the counter stays
@@ -1735,8 +1772,7 @@ async def acquire(self) -> AsyncIterator[DqliteConnection]:
             conn._pool_released = False
             try:
                 try:
-                    with contextlib.suppress(*_POOL_CLEANUP_EXCEPTIONS):
-                        await asyncio.shield(conn.close())
+                    await self._close_best_effort(conn, "acquire-drain-stale-conn")
                 except RuntimeError:
                     # "Event loop is closed" during racing
                     # ``engine.dispose()``, or cross-loop
@@ -2173,21 +2209,21 @@ async def _release(self, conn: DqliteConnection) -> None:
         returned_to_queue = False
         try:
             if self._closed:
-                # Shield the close so an outer cancel mid-cleanup
-                # (e.g. ``asyncio.timeout`` around ``engine.dispose()``)
-                # cannot abort the close mid-``wait_closed`` and orphan
-                # the StreamReader task. ``_POOL_CLEANUP_EXCEPTIONS``
-                # does not include ``CancelledError``; the shield is
-                # the load-bearing guard. Symmetric with every other
-                # close site in this module.
-                with contextlib.suppress(*_POOL_CLEANUP_EXCEPTIONS):
-                    await asyncio.shield(conn.close())
+                # Shield (via ``_close_best_effort``) so an outer cancel
+                # mid-cleanup (e.g. ``asyncio.timeout`` around
+                # ``engine.dispose()``) cannot abort the close mid-
+                # ``wait_closed`` and orphan the StreamReader task.
+                # ``_POOL_CLEANUP_EXCEPTIONS`` does not include
+                # ``CancelledError``; the shield is the load-bearing
+                # guard. ``_POOL_CLEANUP_EXCEPTIONS`` errors are logged
+                # at DEBUG with ``exc_info=True`` (mirrors
+                # ``_initialize_close_unqueued``).
+                await self._close_best_effort(conn, "release-closed")
                 conn._pool_released = True
                 return
 
             if not await self._reset_connection(conn):
-                with contextlib.suppress(*_POOL_CLEANUP_EXCEPTIONS):
-                    await asyncio.shield(conn.close())
+                await self._close_best_effort(conn, "release-reset-rolled-back")
                 conn._pool_released = True
                 return
 
@@ -2199,8 +2235,7 @@ async def _release(self, conn: DqliteConnection) -> None:
             # the conn is unreachable). Mirrors the close-vs-initialize
             # symmetry fix.
             if self._closed:
-                with contextlib.suppress(*_POOL_CLEANUP_EXCEPTIONS):
-                    await asyncio.shield(conn.close())
+                await self._close_best_effort(conn, "release-post-reset-closed")
                 conn._pool_released = True
                 return
 
@@ -2223,8 +2258,7 @@ async def _release(self, conn: DqliteConnection) -> None:
             try:
                 self._pool.put_nowait(conn)
             except asyncio.QueueFull:
-                with contextlib.suppress(*_POOL_CLEANUP_EXCEPTIONS):
-                    await asyncio.shield(conn.close())
+                await self._close_best_effort(conn, "release-queuefull")
                 conn._pool_released = True
             else:
                 conn._pool_released = True

tests/test_pool_release_close_error_debug_logged.py

@@ -0,0 +1,123 @@
+"""Pin: the seven release/drain close sites that previously used
+``contextlib.suppress(*_POOL_CLEANUP_EXCEPTIONS)`` now route through
+``ConnectionPool._close_best_effort``, which logs the absorbed
+exception at DEBUG with ``exc_info=True`` rather than silently
+dropping it.
+
+Pre-fix the sites suppressed silently — an OSError /
+DqliteConnectionError / OperationalError from ``conn.close()`` during
+release/drain dissolved with no trace, asymmetric with
+``_initialize_close_unqueued`` (which logged via ``exc_info=True``).
+An operator investigating "the pool kept hitting close_timeout under
+load" had nothing to find at any verbosity.
+
+This test drives the closed-pool release branch (representative of the
+seven sites) and asserts a DEBUG record naming the site lands with
+``exc_info`` populated. Pairs with
+``test_pool_initialize_unqueued_survivor_close_log.py``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+from unittest.mock import MagicMock
+
+import pytest
+
+from dqliteclient.cluster import ClusterClient
+from dqliteclient.exceptions import DqliteConnectionError
+from dqliteclient.pool import ConnectionPool
+
+
+class _FakeConn:
+    def __init__(self, *, close_side_effect: BaseException | None = None) -> None:
+        self._address = "localhost:9001"
+        self._in_transaction = False
+        self._tx_owner = None
+        self._pool_released = False
+        self._protocol = MagicMock()
+        self._protocol.is_wire_coherent = True
+        self._protocol._writer = MagicMock()
+        self._protocol._writer.transport = MagicMock()
+        self._protocol._writer.transport.is_closing = lambda: False
+        self._protocol._reader = MagicMock()
+        self._protocol._reader.at_eof = lambda: False
+        self._close_side_effect = close_side_effect
+        self.close_calls = 0
+
+    @property
+    def is_connected(self) -> bool:
+        return self._protocol is not None
+
+    async def close(self) -> None:
+        self.close_calls += 1
+        if self._close_side_effect is not None:
+            raise self._close_side_effect
+        self._pool_released = True
+        self._protocol = None  # type: ignore[assignment]
+
+
+def _make_pool_with_fake_cluster(fake_conn: _FakeConn) -> ConnectionPool:
+    async def _connect(**kwargs: Any) -> _FakeConn:
+        return fake_conn
+
+    cluster = MagicMock(spec=ClusterClient)
+    cluster.connect = _connect
+    return ConnectionPool(
+        addresses=["localhost:9001"],
+        min_size=0,
+        max_size=1,
+        timeout=1.0,
+        cluster=cluster,
+    )
+
+
+@pytest.mark.asyncio
+async def test_release_closed_branch_logs_close_error_at_debug(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """The closed-pool release branch routes through
+    ``_close_best_effort``: a ``DqliteConnectionError`` from
+    ``conn.close()`` is absorbed but emits a DEBUG record naming the
+    site (``"pool.release-closed: close error"``) with ``exc_info``
+    populated."""
+    fake = _FakeConn(close_side_effect=DqliteConnectionError("transport broken"))
+    pool = _make_pool_with_fake_cluster(fake)
+
+    cm = pool.acquire()
+    conn = await cm.__aenter__()
+    assert conn is fake
+    pool._closed = True
+
+    with caplog.at_level(logging.DEBUG, logger="dqliteclient.pool"):
+        # Must NOT raise — the helper absorbs _POOL_CLEANUP_EXCEPTIONS.
+        await cm.__aexit__(None, None, None)
+
+    assert fake.close_calls >= 1
+
+    # A DEBUG record named for the site, with exc_info populated.
+    debug_records = [
+        r for r in caplog.records if r.levelno == logging.DEBUG and "close error" in r.message
+    ]
+    assert debug_records, (
+        "expected a DEBUG record naming the release site; "
+        f"saw records={[(r.levelname, r.message) for r in caplog.records]}"
+    )
+    matched = [r for r in debug_records if "release-closed" in r.message]
+    assert matched, (
+        f"expected the release-closed site name in the DEBUG record; "
+        f"got messages={[r.message for r in debug_records]}"
+    )
+    rec = matched[0]
+    assert rec.exc_info is not None
+    assert isinstance(rec.exc_info[1], DqliteConnectionError)
+
+
+def test_close_best_effort_helper_exists_with_logging_shape() -> None:
+    """Static pin: ``ConnectionPool`` exposes ``_close_best_effort``, the
+    DRY helper that replaced the seven ``contextlib.suppress(
+    *_POOL_CLEANUP_EXCEPTIONS)`` sites. Detects accidental removal of
+    the helper or rename that would silently drop the logging on the
+    release path again."""
+    assert hasattr(ConnectionPool, "_close_best_effort")