utils/gatelock/gatelock/_credit_watch.py
Krzysztof kuhy Rudnicki 1194517702
Some checks failed
dependency freshness / dependencies on newest stable (push) Waiting to run
earned_time pre-commit / pre-commit (push) Waiting to run
earned_time tests / test (push) Waiting to run
file length / file-length (push) Waiting to run
md-naming / markdown naming convention (push) Waiting to run
palette drift / palette (push) Waiting to run
repo-contract / repo contract (push) Waiting to run
shared gate tests / gate unit tests (push) Waiting to run
ts_config tests / test (push) Waiting to run
ts_core tests / test (push) Waiting to run
web_ui tests / test (push) Waiting to run
crdt_sync_dart tests / test (push) Has been cancelled
crdt_sync_flutter tests / test (push) Has been cancelled
crdt-sync pre-commit / pre-commit (push) Has been cancelled
crdt-sync tests / test (push) Has been cancelled
focus-project pre-commit / pre-commit (push) Has been cancelled
focus-project tests / test (push) Has been cancelled
freedays pre-commit / pre-commit (push) Has been cancelled
freedays tests / test (push) Has been cancelled
gatelock pre-commit / pre-commit (push) Has been cancelled
gatelock tests / test (push) Has been cancelled
holds pre-commit / pre-commit (push) Has been cancelled
holds tests / test (push) Has been cancelled
leetcode-coach pre-commit / pre-commit (push) Has been cancelled
leetcode-coach tests / test (push) Has been cancelled
music_theory tests / test (push) Has been cancelled
omniroute_offload pre-commit / pre-commit (push) Has been cancelled
sickdays pre-commit / pre-commit (push) Has been cancelled
sickdays tests / test (push) Has been cancelled
sql-drills pre-commit / pre-commit (push) Has been cancelled
sql-drills tests / test (push) Has been cancelled
Add gatelock.watch_credit (0.14.0)
An open lock window never noticed a credit written by another process:
screen-locker opened at 07:55, a workout was credited at 07:59, and the
window stayed up. Gates read the log once at startup.

watch_credit polls the files that carry the credit on the Tk after loop
(one stat per poll, owner verdict only when a file changed), and hands a
done verdict to the owner's close path. Failure mode is closed: an
unreadable file or a raising verdict is logged and retried.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWWfb63jncj9Lca2jeX
2026-11-16 09:03:42 +01:00

123 lines
4.6 KiB
Python

# Copyright (c) 2026 Krzysztof Rudnicki
"""An open lock window notices a credit that landed while it was up.
Born in screen-locker (2026-11-16): the window opened at 07:55, a workout was
credited at 07:59 by a separate daemon, and the open window never noticed --
the startup ladder reads the log once. This is the shared form of that fix, so
every gate that earns its way down can take itself down the same way.
Event-driven on the Tk ``after`` loop, no thread, no dependency. Each poll is
one ``stat`` per watched file; the owner's "is it done today?" verdict (which
may parse and HMAC-check the log) runs only when a file's (mtime, size, inode)
moved, plus once on the first poll. The credit itself was already written by
whoever earned it, so ``on_credit`` writes nothing: it only takes the window
down through the owner's normal close path.
Failure modes, chosen out loud: **fail closed**. A file that cannot be stat'ed
or a verdict that raises is logged and retried at the next poll; the lock stays
up. Only a verdict of True ever lifts it.
"""
from __future__ import annotations
import logging
from typing import TYPE_CHECKING, Final
if TYPE_CHECKING:
from collections.abc import Callable, Sequence
from pathlib import Path
from tkinter import Misc
__all__ = ["CREDIT_POLL_MS", "watch_credit"]
_logger: Final = logging.getLogger(__name__)
# Well inside the 10 s an open window may take to notice a credit.
CREDIT_POLL_MS: Final = 3_000
_Signature = tuple[tuple[int, ...], ...]
# Never equals a real signature, so the first poll always asks.
_UNSEEN: Final[_Signature] = ((-1,),)
_ABSENT: Final[tuple[int, ...]] = ()
# What a verdict or close path may raise on a bad read; anything else is a bug
# and should surface, not be swallowed by a watcher.
_CHECK_ERRORS: Final = (OSError, ValueError, TypeError, LookupError, RuntimeError)
def _signature(paths: Sequence[Path], poll_ms: int) -> _Signature | None:
"""(mtime_ns, size, inode) per path: ``()`` if absent, None if unreadable."""
parts: list[tuple[int, ...]] = []
for path in paths:
try:
stat = path.stat()
except FileNotFoundError:
# A file nobody has written yet is normal, not a fault.
parts.append(_ABSENT)
continue
except OSError as exc:
_logger.warning(
"Could not stat %s while the lock is up (%s) -- keeping the "
"lock and trying again in %d s",
path,
exc,
poll_ms // 1000,
)
return None
parts.append((stat.st_mtime_ns, stat.st_size, stat.st_ino))
return tuple(parts)
def watch_credit(
root: Misc,
paths: Sequence[Path],
is_done: Callable[[], bool],
on_credit: Callable[[], None],
poll_ms: int = CREDIT_POLL_MS,
) -> None:
"""Hand a credit that landed while the window is up to ``on_credit``.
Args:
root: The Tk root whose ``after`` loop drives the polling.
paths: Files whose change can mean a credit landed (the log the owner
reads). Absent files are fine; they count as "not there yet".
is_done: The owner's own "is today satisfied?" check. Called on the
first poll and whenever a watched file changed, never otherwise.
on_credit: Called once when ``is_done`` returns True; should close the
window through its normal path. The watch stops re-arming then.
poll_ms: Interval between polls.
Raises:
ValueError: ``paths`` is empty or ``poll_ms`` is not positive.
An ``is_done`` or ``on_credit`` that raises an OSError, ValueError,
TypeError, LookupError or RuntimeError is logged and retried at the
next poll: one bad read must not end the only thing watching.
"""
if not paths:
msg = "watch_credit needs at least one path to watch (paths is empty)"
raise ValueError(msg)
if poll_ms <= 0:
msg = f"poll_ms must be positive, got {poll_ms}"
raise ValueError(msg)
seen = _UNSEEN
def _tick() -> None:
nonlocal seen
sig = _signature(paths, poll_ms)
if sig is not None and sig != seen:
seen = sig
try:
if is_done():
on_credit()
return
except _CHECK_ERRORS:
_logger.exception(
"Credit check failed while the lock is up -- keeping the "
"lock and trying again in %d s",
poll_ms // 1000,
)
seen = _UNSEEN
root.after(poll_ms, _tick)
root.after(poll_ms, _tick)