utils/gatelock/README.md
Krzysztof kuhy Rudnicki c439f54784
Some checks are pending
file length / file-length (push) Waiting to run
gatelock pre-commit / pre-commit (push) Waiting to run
gatelock tests / test (push) Waiting to run
kuhy_credit drift / drift (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
gatelock: verify the 2026-11-21 lock order
verify_all_lockers now runs six lockers at kuhy's ranks (workout,
book, tutor, diet, focus, LeetCode last), fails when they come up out
of order, and checks each installed locker's rank constant.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 14:54:54 +01:00

181 lines
8.6 KiB
Markdown

# gatelock
Shared fullscreen lock-window + HMAC log-integrity backend, extracted from
three personal automation tools that each independently implemented "lock the
screen with a blocking overlay until a condition is met":
[diet_guard](https://github.com/kuhyx/testsAndMisc/tree/main/python_pkg/diet_guard),
[wake_alarm](https://github.com/kuhyx/testsAndMisc/tree/main/python_pkg/wake_alarm),
and [screen-locker](https://github.com/kuhyx/screen-locker).
## Why
All three reimplemented the same tkinter fullscreen mechanics (overrideredirect,
input grab, VT-switch disable) at different levels of maturity, and the
HMAC-signed-state module had already been hand-copied between two of them
because they live in separate repos. `gatelock` is the one place that logic
now lives.
## Install
```bash
pip install "gatelock @ git+https://github.com/kuhyx/utils@gatelock-v0.1.1#subdirectory=gatelock"
```
## Usage
```python
import tkinter as tk
from gatelock import GateRoot, LockConfig, LockWindow
class MyGate:
def __init__(self, *, demo_mode: bool) -> None:
self.root = GateRoot()
self.root.on_callback_error = self._handle_callback_error
config = LockConfig(mode="soft" if demo_mode else "hard")
self._lock = LockWindow(self.root, config, hooks=self)
self._lock.setup()
# ... build your widgets ...
self._lock.grab_input()
def on_focus_ready(self) -> None:
self.my_entry.focus_force()
def on_callback_error(self) -> None:
self.close()
def on_close(self) -> None:
... # release any hardware/state held while locked
def close(self) -> None:
self._lock.close()
def run(self) -> None:
self._lock.run()
```
`LockConfig`'s `mode` preset bundles the common combination ("soft" = topmost
only, typeable, WM-escapable; "hard" = overrideredirect + global grab +
VT-disable). `overrideredirect` and the `grab=GrabPolicy(kind=..., disable_vt=...,
retry_ms=...)` axes can be set explicitly to reproduce a consumer's exact prior
behavior where it diverges from the preset. Colours, type scale and spacing are
the `palette`, `typography` and `spacing` records (`gatelock.LockPalette` etc.),
overridden as a unit.
`gatelock.log_integrity` ports the HMAC-signed state module used by all three
projects; `DEFAULT_HMAC_KEY_FILE` (`/etc/workout-locker/hmac.key`) is
unchanged so existing signed history keeps verifying.
`gatelock.morning_session.morning_skip` is the one reader of wake-alarm's
signed `morning_session.json` (the wake-early carrot: no lock until the signed
`exempt_until`, 11:00 for a morning completed in time). screen-locker,
leetcode-guard and book-guard all call it; the policy itself stays in
wake-alarm. The arming run waits up to 180 s for a freshly booted PC's
refresher (status paths never wait). Path and retry budget are arguments so
each consumer's tests keep redirecting their own constant.
`gatelock.corner_strip` is the top-right always-on-top status strip for a gate
that is stood down but not done (`build_corner_strip`, `CornerStrip`,
`StripContent`, `corner_rect`, `corner_geometry`). It never grabs input; its
tick ends when the owner's `supply` returns `None`.
`gatelock.watch_credit(root, paths, is_done, on_credit, poll_ms=3000)` lets an
open lock window notice a credit that landed while it was up (a workout or meal
logged elsewhere). One `stat` per path per poll on the Tk `after` loop; the
owner's `is_done()` runs only on the first poll and when a path's (mtime, size,
inode) changed; True calls `on_credit` (the window's normal close) and stops.
A raising `is_done`/`on_credit` or an unreadable path is logged and retried
(fail closed). Pass `poll_ms` of 3000 or less: an open window should notice
inside ~10 s. Generalises screen-locker's `_credit_watch`.
`gatelock.night_lockdown.evening_lockdown_today` answers "has tonight's
evening night-lockdown already happened?" from night-lockdown's
`/var/lib/night-lockdown/locked_at_epoch` (local date today, local time
>= 12:00; the 04:01 morning re-lock does not count). Earner gates
(screen-locker's workout lock, leetcode-guard, book-guard) opt in and do not
re-arm for the rest of such a day; diet-guard does not. Missing or garbage
means "no lockdown" (garbage warns), so the gate locks as before.
`gatelock.held_grabs(claims_dir=None) -> tuple[Claim, ...]` answers "is a
locker's X grab ACTUALLY held right now?": live claims (flock-proved) whose
`grab_held` is true and whose declared grab is not `none`. `grab_held` turns
true only after `grab_set`/`grab_set_global` succeeded, follows each recovery
tick, and is cleared/restored around a deliberate release via
`LockWindow.report_grab_held(held=...)` (or `Arbiter.set_grab_held`) --
leetcode-guard's study mode. It is rewritten in place under the owner's flock.
A claim from a pre-0.11 writer has no key and reads as `grab != "none"`. Root
has no `XDG_RUNTIME_DIR`, so a root reader passes the user's dir
(`/run/user/1000/gatelock/claims`).
`LockWindow` yields to a system credential prompt that holds the X grab. If the
global grab stays unobtainable for more than 2 s AND a mapped window whose
WM_CLASS is in `gatelock._prompt_names.SYSTEM_PROMPT_CLASSES` (`gcr-prompter`,
`pinentry*`, polkit agents, ssh-askpass variants) is on screen, that prompt's
top-level window is raised above the lock and the lock's periodic re-raise
stops covering it while it stays mapped. The lock stays mapped, VT switching
stays disabled and the grab keeps being retried; once the grab is taken the lock
is back on top. Any other grab holder (a fullscreen game) never gets this.
`scripts/verify_prompt_yield.py` proves it on a private Xvfb (never `:0`).
Lockers that start together do not fight. `wait_for_turn` waits
`STARTUP_GRACE_SECONDS` (1.5 s) after `publish()` before its first check, so
simultaneous starters see each other. An armed lock also steps back (`_stepback`)
when a strictly higher-ranked, live claim that locks at least as firmly appears
later: it hides, releases the grab and its holder lock (the claim stays, so
lower ranks keep queueing), waits windowless, and re-arms fully once nothing
outranks it. `scripts/verify_all_lockers.py` checks this with six real
processes on a private Xvfb. It also fails unless the locks come up in
kuhy's order (2026-11-21: workout 200, book 175, tutor 150, diet 130,
focus 128, LeetCode 125 last) and every installed locker's own rank
constant matches that table (`scripts/locker_ranks.py`, runnable alone).
## Error and slow-wait reporting
`gatelock.error_report` is the Python reporter of the shared app-errors pipeline
(utils `DOCS-app-errors.md`). Call it once at start-up, then watch the Tk loop:
```python
from gatelock import error_report
rep = error_report.install("leetcode-guard", "kuhyx/leetcode-guard")
error_report.watch_stalls(root, rep) # a frozen loop over 1 s -> perf.slow
with rep.wait("coach.load"): # or rep.begin(...).end() across callbacks
...
```
Uncaught, thread and Tk callback errors and waits over 1 s go to
`~/.local/state/app-errors-spool/<app>.jsonl`. The `app-errors` ingest timer
turns them into board tickets. Nothing shows on screen.
## Evening gate chain
`python3 -m gatelock.evening_chain pending|run` (0.16.0) runs book, then tutor,
then LeetCode in front of night lockdown. Needs the `evening` extra
(earned-time, freedays, sickdays); only this CLI imports them.
- `pending` prints the unpaid rungs. Exit 0 some rung is unpaid; 1 nothing
to do (all paid, free day, sick day, or 23:00 and later); 2 could not
check (unreadable ledger or key, any exception; stderr says why) -- it
fails closed, so root enters lockdown. Reading and LeetCode use
`earned_time.done_today`; the tutor is quota-based
(`credit_units >= max_units`). The LeetCode rung is pending only while
payable: a day settled by any signed `charge:<day>` row (escape hatch,
outage) can never earn the bonus, so it is not listed. Cheap: three small reads, root runs it
every minute.
- `run` runs each unpaid rung's gate (`GATE_COMMANDS`, all `--production
--evening`) and re-checks before each. A gate's exit 10
(`EXIT_END_EVENING`) stops the chain with 0; 3 (`EXIT_NO_X`) exits 3; a
gate killed at 23:00 or nothing left exits 0; a failing gate (or one that
exits 0 with its rung still unpaid) is skipped, and two in a row exit 1.
- `RANK_EVENING_GATE` = 150 sits between the screen-locker and diet-guard.
- `systemd/evening-gates.service` is the user unit root starts;
`install_evening_gates.sh` copies it and reloads, and never enables it.
## Development
```bash
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
pytest
pre-commit install && pre-commit install --hook-type pre-push
```