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) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LJ5YnA3CERitQ57HjMu2Qz
This commit is contained in:
Krzysztof Rudnicki 2026-08-21 13:07:37 +02:00
parent 0173f4c56c
commit c7371d7e0d
8 changed files with 248 additions and 16 deletions

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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