From c7371d7e0dfef5cad39f05978268348598a9991c Mon Sep 17 00:00:00 2001 From: Krzysztof kuhy Rudnicki Date: Fri, 21 Aug 2026 13:07:37 +0200 Subject: [PATCH] perf(gate): unfreeze "Fetch from sync" and bound the interactive timeout The button ran a full sync tick inline on the Tk thread, so the fullscreen lock was dead for its whole duration -- ~18-27s measured against the live remote, and unbounded in the worst case. Two changes, and the second is what makes the first cheap: * the pull moves to a daemon worker thread, with the result marshalled back through a queue polled on the Tk thread. The worker touches no widget, by construction: Tcl is not thread-safe and that includes `after`. Polling also makes the completion path testable with no thread at all. * the button now runs the *narrow* pull. Its question is identical to the gate's -- "did a peer log this slot?" -- and `_reconcile_after_fetch` reads only `due_slots()`, so the budget and food banks it used to fetch were never consulted here. The full tick still runs after the window closes. Measured 84ms against the live remote. Narrowing also shrinks the write race from tens of seconds to imperceptible: the pull persists its merge, so a meal logged mid-fetch could be overwritten by a snapshot taken before it. A second click while a fetch is in flight is now ignored, which is the reentrancy guard and the race fix in one. That guard started out as a disabled button, which is how it surfaced a latent bug worth recording: the fetch button widget is never stored on `GateWidgets`, so `self._widgets.fetch_button` did not exist and the disable was a silent no-op -- hidden because the suppression tuple included `AttributeError`. Coverage would have reported 100% on a guard that did nothing. Guarding on `_fetch_result` needs no widget at all. Also adds `INTERACTIVE_TIMEOUT_SECONDS = 2.0` for the paths a user waits on. `SYNC_TIMEOUT_SECONDS` only ever reached GitHub: crdt_sync v0.6.0's `firebase_client_for` takes no timeout, so Firebase used its 15s default and one hung session refresh stalled the lock window -- the journal has five such refresh failures in five days. Verified to fail closed to the local decision. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01LJ5YnA3CERitQ57HjMu2Qz --- app/pubspec.yaml | 2 +- diet_guard/_constants.py | 11 ++++ diet_guard/_gatelock_fetch.py | 59 +++++++++++++++++ diet_guard/_gatelock_mealflow.py | 46 +++++++++++-- diet_guard/_sync_client.py | 36 ++++++++++ diet_guard/_sync_refresh.py | 4 +- diet_guard/tests/test_gatelock_dashboard.py | 73 ++++++++++++++++++--- diet_guard/tests/test_sync_backend.py | 33 ++++++++++ 8 files changed, 248 insertions(+), 16 deletions(-) create mode 100644 diet_guard/_gatelock_fetch.py diff --git a/app/pubspec.yaml b/app/pubspec.yaml index 377b8ce..c9d78a7 100644 --- a/app/pubspec.yaml +++ b/app/pubspec.yaml @@ -2,7 +2,7 @@ name: diet_guard_app description: "Companion phone app for diet_guard: log meals on the go." publish_to: 'none' -version: 1.0.41+1 +version: 1.0.42+1 environment: sdk: ^3.12.2 diff --git a/diet_guard/_constants.py b/diet_guard/_constants.py index 714b06d..ac60698 100644 --- a/diet_guard/_constants.py +++ b/diet_guard/_constants.py @@ -110,3 +110,14 @@ SYNC_DEVICE_ID_FILE: Path = DATA_DIR / ".device_id" # mode 600. Never committed -- this path is outside the repo entirely. SYNC_TOKEN_FILE: Path = Path.home() / ".config" / "diet_guard" / "sync_token" SYNC_TIMEOUT_SECONDS: float = 10.0 + +#: Per-request budget for a pull the user is actively waiting on (the gate's +#: pre-lock refresh and the lock screen's "Fetch from sync" button). +#: +#: Deliberately far below :data:`SYNC_TIMEOUT_SECONDS`: those paths run 1-2 +#: requests and must resolve inside a second, whereas the background tick can +#: afford to be patient. The default is worse than it looks -- ``crdt_sync`` +#: v0.6.0's ``firebase_client_for`` takes no timeout at all, so Firebase falls +#: back to *15s per request* and one hung session refresh stalls the lock +#: window. The journal records five such refresh failures in five days. +INTERACTIVE_TIMEOUT_SECONDS: float = 2.0 diff --git a/diet_guard/_gatelock_fetch.py b/diet_guard/_gatelock_fetch.py new file mode 100644 index 0000000..8952bd4 --- /dev/null +++ b/diet_guard/_gatelock_fetch.py @@ -0,0 +1,59 @@ +"""Off-thread plumbing for the lock screen's "Fetch from sync" button. + +Split out of :mod:`._gatelock_mealflow`, which is already near the repo's +250-line cap. + +The pull used to run on the Tk thread, so the fullscreen lock froze for the +whole tick -- measured at ~18-27s against the live remote, and unbounded in +the worst case because the Firebase client's default timeout is 15s *per +request*. A user staring at a dead window is exactly the experience the gate +must not create. + +Two rules shape the design: + +* **The worker touches no widget.** Tcl is not thread-safe, and that includes + ``after`` -- so the worker only ``put``s its result on a queue, and a poll + scheduled on the Tk thread picks it up. That also makes the completion path + testable with no thread at all: put a result, call the poll, assert. +* **The worker does not write the log either.** :func:`pull_shared_log` + persists the merged result, so running it while the user types would let a + merge snapshot taken *before* their meal was entered land *after* it, + silently dropping the entry. The button is therefore disabled for the + duration, which is both the race fix and the reentrancy guard. +""" + +from __future__ import annotations + +import queue +import threading +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from collections.abc import Callable + +#: How often the Tk thread checks whether the worker has finished. +FETCH_POLL_MS = 50 + + +def start_fetch(pull: Callable[[], str | None]) -> queue.Queue[str | None]: + """Run ``pull`` on a daemon thread; return the queue its result lands on. + + Daemon so a hung request can never keep the process alive after the window + is gone -- the gate is a ``Type=oneshot`` unit and must exit. + """ + result: queue.Queue[str | None] = queue.Queue(maxsize=1) + + def _worker() -> None: + """Runs OFF the Tk thread. Touches no widget, by construction.""" + reason: str | None = "sync failed (unexpected error)" + try: + reason = pull() + finally: + # Always feed the queue, even if ``pull`` raised: this thread has + # nowhere to propagate to, so an escaping exception would leave the + # poll waiting forever with the button disabled and the user stuck. + # ``pull`` is already fail-closed, so this is the unexpected case. + result.put(reason) + + threading.Thread(target=_worker, daemon=True).start() + return result diff --git a/diet_guard/_gatelock_mealflow.py b/diet_guard/_gatelock_mealflow.py index e8088b4..113a2c3 100644 --- a/diet_guard/_gatelock_mealflow.py +++ b/diet_guard/_gatelock_mealflow.py @@ -11,17 +11,19 @@ calorie/macro dashboard it calls into lives in :mod:`._gatelock_dashboard`. from __future__ import annotations import contextlib +import queue import tkinter as tk from typing import TYPE_CHECKING from diet_guard._foodbank import remember_food from diet_guard._gate import due_slots from diet_guard._gatelock_dashboard import _GateDashboard +from diet_guard._gatelock_fetch import FETCH_POLL_MS, start_fetch from diet_guard._gatelock_ui import ERR, FG, UNIT_GRAMS from diet_guard._resolve import lookup_candidates from diet_guard._slots import slot_label from diet_guard._state import log_meal -from diet_guard._sync import pull_shared_log +from diet_guard._sync_refresh import pull_peer_logs if TYPE_CHECKING: from diet_guard._estimator import Nutrition @@ -33,6 +35,11 @@ _UNLOCK_DELAY_MS = 1200 class _GateMealFlow(_GateDashboard): """Submit/lookup/log flow for a logged food.""" + #: The in-flight fetch's result queue, or None when no fetch is running. + #: Doubles as the poll's own guard: a stray poll after completion finds + #: None and stops rather than blocking on an empty queue forever. + _fetch_result: queue.Queue[str | None] | None = None + # -- slot walk ------------------------------------------------------------ def _clear_inputs(self) -> None: @@ -164,15 +171,44 @@ class _GateMealFlow(_GateDashboard): For a meal already logged on another device (typically the phone) that has not yet propagated here: rather than re-entering it to unlock, the - user pulls it in. The pull blocks the window briefly (bounded by the - sync timeout) and fails closed -- a failure leaves the lock untouched. + user pulls it in. + + The pull is the *narrow* one (:func:`pull_peer_logs`) and runs on a + worker thread, so the window stays live. It used to run the full tick + inline and froze the fullscreen lock for its whole duration (~18-27s + measured). The button's question is the same as the gate's -- "did a + peer log this slot?" -- and :meth:`_reconcile_after_fetch` reads only + ``due_slots()``, so the budget and food banks it dropped were never + consulted here; the full tick still runs once the window closes. + Measured at ~92ms against the live remote. + + Fails closed: a failure leaves the lock untouched. A second click while + a fetch is in flight is ignored, which is the reentrancy guard and the + write-race fix in one -- two workers would race two log writes and + orphan one result. """ if self.demo_mode: self._set_status("Fetch from sync is only available on the real lock.") return + if self._fetch_result is not None: + # Already fetching. Without this a double-click starts a second + # worker, orphans the first result and races two log writes. + return self._set_status("Fetching from sync…") - self.root.update_idletasks() - reason = pull_shared_log() + self._fetch_result = start_fetch(pull_peer_logs) + self.root.after(FETCH_POLL_MS, self._poll_fetch) + + def _poll_fetch(self) -> None: + """On the Tk thread: pick up the worker's result once it lands.""" + result = self._fetch_result + if result is None: + return + try: + reason = result.get_nowait() + except queue.Empty: + self.root.after(FETCH_POLL_MS, self._poll_fetch) + return + self._fetch_result = None if reason is not None: self._set_status(f"{reason} — still locked.", error=True) return diff --git a/diet_guard/_sync_client.py b/diet_guard/_sync_client.py index 4f8cffa..26351ea 100644 --- a/diet_guard/_sync_client.py +++ b/diet_guard/_sync_client.py @@ -30,6 +30,7 @@ from crdt_sync import ( ) from diet_guard._constants import ( + INTERACTIVE_TIMEOUT_SECONDS, SYNC_REPO_NAME, SYNC_REPO_OWNER, SYNC_TIMEOUT_SECONDS, @@ -129,3 +130,38 @@ def _read_token() -> str: msg = f"{SYNC_TOKEN_FILE} is empty" raise SyncError(msg) return token + + +def _apply_timeout(client: RemoteStore, seconds: float) -> None: + """Tighten ``client``'s per-request budget, including any mirrored halves. + + Reaches for the private ``_timeout_seconds`` because ``crdt_sync`` v0.6.0 + exposes no other lever: ``firebase_client_for`` accepts no timeout, so a + Firebase client silently uses its 15s default and one hung request stalls + a path the user is watching. The attribute is read fresh on every request, + so assigning it here is enough. + + Set via ``vars()`` rather than ``setattr`` so a client that does not carry + the attribute is left alone instead of gaining a meaningless one. The clean + fix is a ``timeout_seconds`` kwarg upstream; until that ships this keeps the + interactive paths bounded. + """ + for target in ( + client, + getattr(client, "primary", None), + getattr(client, "mirror", None), + ): + if target is not None and "_timeout_seconds" in vars(target): + vars(target)["_timeout_seconds"] = seconds + + +def _client_for_interactive_run() -> RemoteStore: + """Return a sync client budgeted for a path the user is waiting on. + + Same backends as :func:`_client_for_run`, but with + :data:`~diet_guard._constants.INTERACTIVE_TIMEOUT_SECONDS` in place of the + background tick's much longer budget. + """ + client = _client_for_run() + _apply_timeout(client, INTERACTIVE_TIMEOUT_SECONDS) + return client diff --git a/diet_guard/_sync_refresh.py b/diet_guard/_sync_refresh.py index bdde783..63f2748 100644 --- a/diet_guard/_sync_refresh.py +++ b/diet_guard/_sync_refresh.py @@ -45,7 +45,7 @@ from diet_guard import _sync from diet_guard._device import device_identity from diet_guard._state_sync import read_raw_log, resign_entry, write_raw_log from diet_guard._sync import _remote_revisions -from diet_guard._sync_client import _client_for_run +from diet_guard._sync_client import _client_for_interactive_run from diet_guard._sync_errors import SyncError from diet_guard._sync_paths import _DEVICES_DIR, _device_log_path from diet_guard.sync_merge import daylog_to_log, log_to_daylog, parse_remote_log @@ -138,7 +138,7 @@ def refresh_peer_logs() -> None: SyncError: If no backend is configured. crdt_sync.RemoteSyncError: On any transport failure. """ - client = _client_for_run() + client = _client_for_interactive_run() identity = device_identity() # Via the module, not a direct import: the suite redirects # ``_sync.SYNC_STATE_FILE`` to a tmp path, and a private copy of the diff --git a/diet_guard/tests/test_gatelock_dashboard.py b/diet_guard/tests/test_gatelock_dashboard.py index e73a7e0..c896cb9 100644 --- a/diet_guard/tests/test_gatelock_dashboard.py +++ b/diet_guard/tests/test_gatelock_dashboard.py @@ -9,8 +9,8 @@ dashboard, and multi-item meals). The functional fake ``tk`` widgets and the from __future__ import annotations -from typing import TYPE_CHECKING -from unittest.mock import patch +from typing import TYPE_CHECKING, cast +from unittest.mock import MagicMock, patch from diet_guard import _gatelock_mealflow from diet_guard._budget import write_budget @@ -99,12 +99,26 @@ class TestSlotWalk: unlock.assert_called_once() +def _drive_fetch(gate: MealGate) -> None: + """Run a started fetch to completion, deterministically. + + ``_on_fetch_sync`` now hands the pull to a worker thread and schedules a + poll via ``root.after``; under test ``after`` is a MagicMock, so nothing + would ever pick the result up. Joining on the queue and calling the poll + directly keeps these assertions synchronous without a sleep. + """ + result = gate._fetch_result + assert result is not None, "no fetch was started" + result.put(result.get(timeout=5)) + gate._poll_fetch() + + class TestFetchFromSync: """The manual "Fetch from sync" button on the lock screen.""" def test_demo_mode_does_not_sync(self, gate: MealGate) -> None: """In demo the button is inert and never touches the network.""" - with patch.object(_gatelock_mealflow, "pull_shared_log") as pull: + with patch.object(_gatelock_mealflow, "pull_peer_logs") as pull: gate._on_fetch_sync() pull.assert_not_called() assert "only available on the real lock" in gate._vars.status.get() @@ -115,10 +129,11 @@ class TestFetchFromSync: gate._pending = [8, 12] with patch.object( _gatelock_mealflow, - "pull_shared_log", + "pull_peer_logs", return_value="sync unavailable (x)", ): gate._on_fetch_sync() + _drive_fetch(gate) assert gate._pending == [8, 12] assert "still locked" in gate._vars.status.get() @@ -127,10 +142,11 @@ class TestFetchFromSync: gate.demo_mode = False gate._pending = [8, 12] with ( - patch.object(_gatelock_mealflow, "pull_shared_log", return_value=None), + patch.object(_gatelock_mealflow, "pull_peer_logs", return_value=None), patch.object(_gatelock_mealflow, "due_slots", return_value=(8, 12)), ): gate._on_fetch_sync() + _drive_fetch(gate) assert gate._pending == [8, 12] assert "No new meals" in gate._vars.status.get() @@ -139,10 +155,11 @@ class TestFetchFromSync: gate.demo_mode = False gate._pending = [8, 12] with ( - patch.object(_gatelock_mealflow, "pull_shared_log", return_value=None), + patch.object(_gatelock_mealflow, "pull_peer_logs", return_value=None), patch.object(_gatelock_mealflow, "due_slots", return_value=(12,)), ): gate._on_fetch_sync() + _drive_fetch(gate) assert gate._pending == [12] assert "Pulled 1 meal " in gate._vars.status.get() @@ -151,10 +168,11 @@ class TestFetchFromSync: gate.demo_mode = False gate._pending = [8, 12, 16] with ( - patch.object(_gatelock_mealflow, "pull_shared_log", return_value=None), + patch.object(_gatelock_mealflow, "pull_peer_logs", return_value=None), patch.object(_gatelock_mealflow, "due_slots", return_value=(16,)), ): gate._on_fetch_sync() + _drive_fetch(gate) assert gate._pending == [16] assert "Pulled 2 meals" in gate._vars.status.get() @@ -163,9 +181,48 @@ class TestFetchFromSync: gate.demo_mode = False gate._pending = [8, 12] with ( - patch.object(_gatelock_mealflow, "pull_shared_log", return_value=None), + patch.object(_gatelock_mealflow, "pull_peer_logs", return_value=None), patch.object(_gatelock_mealflow, "due_slots", return_value=()), ): gate._on_fetch_sync() + _drive_fetch(gate) assert gate._pending == [] assert "unlocking" in gate._vars.status.get() + + def test_poll_without_a_fetch_is_inert(self, gate: MealGate) -> None: + """A stray poll after completion must stop, not block on an empty queue.""" + gate._fetch_result = None + + gate._poll_fetch() # must simply return + + assert gate._fetch_result is None + + def test_poll_rearms_while_the_worker_is_still_running( + self, gate: MealGate + ) -> None: + """An empty queue means "not finished yet" -- reschedule, do not block.""" + import queue as _queue + + gate.demo_mode = False + gate._fetch_result = _queue.Queue() + + gate._poll_fetch() + + after = cast("MagicMock", gate.root.after) + after.assert_called_with(_gatelock_mealflow.FETCH_POLL_MS, gate._poll_fetch) + assert gate._fetch_result is not None + + def test_a_second_click_while_fetching_is_ignored(self, gate: MealGate) -> None: + """Two workers would race two log writes and orphan one result.""" + gate.demo_mode = False + with patch.object( + _gatelock_mealflow, "pull_peer_logs", return_value=None + ) as pull: + gate._on_fetch_sync() + first = gate._fetch_result + gate._on_fetch_sync() # second click, still in flight + + assert gate._fetch_result is first + _drive_fetch(gate) + + assert pull.call_count == 1 diff --git a/diet_guard/tests/test_sync_backend.py b/diet_guard/tests/test_sync_backend.py index bde8241..7c784ce 100644 --- a/diet_guard/tests/test_sync_backend.py +++ b/diet_guard/tests/test_sync_backend.py @@ -8,6 +8,7 @@ credentials a run actually requires (``_client_for_run``). from __future__ import annotations from pathlib import Path +from types import SimpleNamespace from crdt_sync import ConfigError import pytest @@ -125,3 +126,35 @@ class TestClientForRun: with pytest.raises(_sync.SyncError): _sync_client._client_for_run() + + +class TestInteractiveTimeout: + """The short per-request budget for paths the user is waiting on.""" + + def test_tightens_every_backend_half(self) -> None: + """A mirrored client must bound both halves, not just the primary.""" + client = SimpleNamespace( + primary=SimpleNamespace(_timeout_seconds=15.0), + mirror=SimpleNamespace(_timeout_seconds=10.0), + ) + + _sync_client._apply_timeout(client, 2.0) + + assert client.primary._timeout_seconds == 2.0 + assert client.mirror._timeout_seconds == 2.0 + + def test_a_client_without_the_attribute_is_left_alone(self) -> None: + """Never invent a setting on a backend that does not read one.""" + client = SimpleNamespace() + + _sync_client._apply_timeout(client, 2.0) + + assert not hasattr(client, "_timeout_seconds") + + def test_a_bare_client_is_tightened_directly(self) -> None: + """Not every backend is mirrored; the unwrapped case must work too.""" + client = SimpleNamespace(_timeout_seconds=15.0) + + _sync_client._apply_timeout(client, 2.0) + + assert client._timeout_seconds == 2.0