Register find_leader done-callback before slot insertion

The single-flight body in find_leader previously inserted the task
into the shared slot map, then registered the done-callback. A
signal-driven interrupt (KeyboardInterrupt / SystemExit raised by
a signal handler at any bytecode boundary between the two
statements) could leave the slot pointing at a task whose
completion is never observed by _clear_slot — surfacing as a
"Task exception was never retrieved" warning at GC time.

Reorder so add_done_callback runs before the slot insertion. The
callback is safe on a not-yet-started task; _clear_slot's
"only delete if it still points at us" guard already handles the
case where the slot was never set. The race window is closed by
construction.

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

Author: antoineleclair

src/dqliteclient/cluster.py

@@ -205,7 +205,6 @@ async def find_leader(self, *, trust_server_heartbeat: bool = False) -> str:
             task = asyncio.create_task(
                 self._find_leader_impl(trust_server_heartbeat=trust_server_heartbeat)
             )
-            self._find_leader_tasks[key] = task
 
             def _clear_slot(t: asyncio.Task[str]) -> None:
                 # Clear the slot only if it still points at THIS task —
@@ -228,7 +227,18 @@ def _clear_slot(t: asyncio.Task[str]) -> None:
                     with contextlib.suppress(BaseException):
                         t.exception()
 
+            # Register the done-callback BEFORE inserting into the
+            # shared slot so a signal-driven interrupt (KI / SystemExit
+            # raised by a signal handler at any bytecode boundary)
+            # between ``create_task`` and ``add_done_callback`` cannot
+            # leave the slot pointing at a task whose completion is
+            # never observed. ``add_done_callback`` is safe on a
+            # not-yet-started task; the callback fires regardless of
+            # slot state, and ``_clear_slot``'s "only delete if it
+            # still points at us" guard handles the case where the
+            # slot was never set.
             task.add_done_callback(_clear_slot)
+            self._find_leader_tasks[key] = task
         # Shield so a caller's outer cancel does not kill the shared
         # task; the cancel still propagates to the calling coroutine
         # via ``await asyncio.shield``.

tests/test_find_leader_done_callback_registered_before_slot_insert.py

@@ -0,0 +1,36 @@
+"""Pin: ``find_leader`` registers its done-callback BEFORE inserting
+the task into the shared slot map.
+
+The reverse order (slot insert → add_done_callback) opens a
+race window: a signal-driven interrupt (KeyboardInterrupt /
+SystemExit raised by a signal handler at any bytecode boundary
+between the two statements) leaves the slot pointing at a task
+whose completion is never observed by ``_clear_slot``.
+
+This test inspects the source order via the closure-captured
+function bytecode order; a future refactor that reverts the
+ordering will fail this pin.
+"""
+
+from __future__ import annotations
+
+import inspect
+
+from dqliteclient.cluster import ClusterClient
+
+
+def test_done_callback_registered_before_slot_insert() -> None:
+    """Inspect the find_leader source: ``add_done_callback`` must
+    appear before ``self._find_leader_tasks[key] = task`` in the
+    ``if task is None or task.done():`` branch."""
+    source = inspect.getsource(ClusterClient.find_leader)
+    callback_idx = source.find("add_done_callback")
+    slot_assign_idx = source.find("self._find_leader_tasks[key] = task")
+    assert callback_idx > 0, "add_done_callback registration site must exist"
+    assert slot_assign_idx > 0, "slot insert site must exist"
+    assert callback_idx < slot_assign_idx, (
+        "find_leader must register the done-callback before inserting "
+        "the task into the shared slot map; otherwise a signal-driven "
+        "interrupt between the two statements leaks an unobserved-"
+        "exception task"
+    )