diet-guard/diet_guard/_gatelock_kuchnia.py
Krzysztof kuhy Rudnicki 03b6a455cb Auto-log due catering before the lock
kuhy's 2026-11-17 override of "delivered is not eaten": before the lock
opens, the PC logs the due slots' dishes by id uuid5(kuchnia📅key),
shared with the phone (fixture-pinned).

Failure paths:
- fetch error, no credentials, > 5 s: fail-closed, nothing is logged,
  the lock opens as before, reason emitted and logged.
- log write error (OSError/ValueError): fail-closed, same.
- gate --check: never logs (a decision, not a write).
- an undone (tombstoned) entry counts as logged: fail-closed against
  resurrecting a meal kuhy removed.
- publish outage after a clearing auto-log: fail-open by design, the
  local entry stays and the reason is emitted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWZHWP4KZ6x5TcXDBFC
2026-11-17 21:42:34 +01:00

92 lines
3.8 KiB
Python

"""Off-thread catering fetch for the lock screen's "Load delivery" button.
Its own module because :mod:`diet_guard._gatelock_mealflow` is already at the
repo's 250-line cap, and because the worker contract here is worth stating
once, plainly.
Modelled on :mod:`diet_guard._gatelock_fetch`, but it cannot reuse
:func:`~diet_guard._gatelock_fetch.start_fetch`: that is typed
``Callable[[], str | None] -> Queue[str | None]`` and this fetch returns
*dishes*. Squeezing them through by stashing results on the instance from the
worker would reintroduce exactly the cross-thread state that module's docstring
exists to forbid, so the pattern is copied rather than bent:
* **The worker touches no widget.** Tcl is not thread-safe, and that includes
``after`` -- the worker only ``put``s 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 always feeds the queue**, even if the call raises. It has
nowhere to propagate to, so an escaping exception would leave the poll
waiting forever with the button disabled and the user stuck behind the lock.
* **Daemon thread**, 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.
Nothing here logs anything. The fetch only *offers* dishes; writing entries is
a separate, explicitly confirmed step (:mod:`diet_guard._kuchnia_log`), or the
tap-free pre-lock auto-log (:mod:`diet_guard._kuchnia_autolog`).
"""
from __future__ import annotations
from collections.abc import Callable
from contextlib import suppress
import queue
import threading
from typing import TYPE_CHECKING, NamedTuple
if TYPE_CHECKING: # pragma: no cover - typing only
from collections.abc import Sequence
from datetime import date
from diet_guard._kuchnia_parse import Dish
#: What ``_kuchnia_import.refresh_delivery`` looks like to this module.
RefreshFn = Callable[["date"], tuple["Sequence[Dish]", "str | None"]]
class DeliveryResult(NamedTuple):
"""What the worker hands back: the dishes, or why there are none."""
dishes: tuple[Dish, ...]
reason: str | None
#: Reported when the worker itself fails unexpectedly. ``refresh_delivery`` is
#: already fail-closed, so reaching this means a bug rather than an outage.
UNEXPECTED = "catering fetch failed (unexpected error)"
def start_delivery_fetch(
refresh: RefreshFn,
day: date,
) -> queue.Queue[DeliveryResult]:
"""Run ``refresh(day)`` on a daemon thread; return its result queue.
Args:
refresh: A ``refresh_delivery``-shaped callable returning
``(dishes, reason)``. Passed in rather than imported so the gate
can be tested without an HTTP stack.
day: The delivery date to fetch.
Returns:
A queue that will receive exactly one :class:`DeliveryResult`.
"""
result: queue.Queue[DeliveryResult] = queue.Queue(maxsize=1)
def _worker() -> None:
"""Runs OFF the Tk thread. Touches no widget, by construction."""
outcome = DeliveryResult(dishes=(), reason=UNEXPECTED)
# ``refresh`` is already fail-closed, so an exception here is a bug --
# but it must not escape this thread. There is nowhere to propagate to,
# so it would surface only as an unraisable-thread warning while the
# poll waits forever and the user stays stuck behind the lock.
# ``suppress`` rather than a broad ``except``; the pre-seeded UNEXPECTED
# outcome is what reaches the window.
with suppress(Exception):
dishes, reason = refresh(day)
outcome = DeliveryResult(dishes=tuple(dishes), reason=reason)
result.put(outcome)
threading.Thread(target=_worker, daemon=True).start()
return result