Files
MeshTerm/meshterm/core/watch_store.py
T
Jean-Pierre MartineauandClaude Opus 5 92d31a3191 Every file is spelled the way the formatter spells it
`ruff format .` across the repo: 153 files, no behaviour change. This is the
second gate CONTRIBUTING.md promises, and until now it reported 154 files needing
reformat — so a first contributor ran the command the guide told them to run and
could not tell their own diff from the background.

Landed on its own, with nothing else in it, because a whole-repo reformat is only
safe to skip past in blame if it is provably nothing but layout. It was checked
that way rather than assumed: every changed file was formatted in memory and
compared by full `ast.dump()`, and 152 of 153 come out structurally identical
(the one exception was a docstring opening on a quote character, fixed in the
commit before this one). The string and comment token streams were diffed
separately, so a quote flip or an edited comment could not hide inside a
re-layout — five quote-style normalisations and sixteen implicit-concatenation
joins, all value-identical, and one commented-out line gaining the space after
its `#`. `meshterm specimen` is byte-identical on both platforms, and the suite
is 1888 green, gallery gate and `test_theme16` included.

What actually changed, in order of how much of the diff it is: wrapped calls and
signatures rejoin onto one line where they fit inside the hundred columns; the
magic trailing comma expands what it is there to expand; complex slices gain
their spaces (`[len(noise) :]`); a few redundant parens go. The tables that are
laid out to be read were fenced in the previous commit and are untouched here.

The aligned trailing-comment column is gone from about ninety lanes that were not
fenced — including the `heat.*` ladder in `MESH_THEME`, which cannot be fenced
where it sits. Every comment stays on the entry it describes, so nothing there
reads wrong; it just no longer lines up.

Add this commit to `.git-blame-ignore-revs`, which follows immediately.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-07 01:07:19 -04:00

456 lines
17 KiB
Python

"""Persistence for the Watchtower: watched nodes, their rules, and the alert log.
The Watchtower (see :mod:`meshterm.services.watchtower`) is a passive sentinel: the user
stars the nodes they care about — the repeater on the roof, the gateway across town —
and rules watch what the always-on event hub already hears. This store remembers, per
watched node (keyed by the 12-hex canonical id observations use), the rule settings and
the last-heard mark the silence rule counts from, plus the rolling alert log and its
acknowledged state, so an alarm raised overnight is still waiting in the morning even
across a restart.
Like the remembered devices (:mod:`meshterm.core.device_store`), this is global machine
state in a small JSON file (``<config_dir>/watchtower.json``) rather than the
per-invocation SQLite database. Reads are served from memory after the first load — the
header badge reads the unacked count on every repaint — and the packet-driven
``note_heard`` writes are throttled so a busy mesh doesn't grind the disk.
"""
from __future__ import annotations
import json
import time
from dataclasses import dataclass, field
from datetime import datetime
from pathlib import Path
from .models import utcnow
#: Silence-rule choices offered in the editor, in hours (:data:`OFF` disables it).
SILENCE_CHOICES_H = (1, 3, 6, 12, 24, 48)
#: Default silence threshold: half a day covers nodes that only advertise daily-ish
#: without crying wolf over a quiet afternoon. It is the *code's* default; what a newly
#: starred node actually gets is the ``watch_silence_hours`` preference, which defaults
#: to this (see :mod:`meshterm.core.preferences`).
DEFAULT_SILENCE_HOURS = 12
#: The stored value meaning "this rule is off".
OFF = 0
#: How many alerts the log retains (oldest dropped first) — the code's default behind
#: the ``watch_alerts_kept`` preference.
ALERT_CAP = 200
#: Minimum seconds between disk flushes for the packet-driven last-heard updates.
_FLUSH_EVERY_S = 60.0
@dataclass(slots=True)
class WatchedNode:
"""One starred node: its rules and the marks the rules count from.
Attributes:
key: The node's canonical 12-hex id (what observations carry).
name: Display label, refreshed whenever the node is heard with a name.
silence_hours: Hours of silence before the alarm (:data:`OFF` disables it).
snr_watch: Whether the SNR-sag rule watches this node's receptions.
last_heard: When the node was last heard (seeded at watch time so the
silence countdown is armed immediately).
silent_since: Set while a silence alarm is active, so it fires once and
re-arms only after the node is heard again.
node_type: The node's advertised type at star time (a ``NODE_TYPE_*``
constant), for the watchlist's type glyph; ``None`` for entries starred
before the field existed (the screen falls back to the contact table).
"""
key: str
name: str
silence_hours: int = DEFAULT_SILENCE_HOURS
snr_watch: bool = True
last_heard: datetime | None = None
silent_since: datetime | None = None
node_type: int | None = None
@dataclass(slots=True)
class Alert:
"""One raised alert, kept until it scrolls off the capped log.
Attributes:
ident: Monotonic id (stable across restarts) used to acknowledge it.
when: When the rule tripped.
kind: ``silence`` / ``recovered`` / ``snr`` / ``new-node``.
label: The node's display label at the time.
message: The human-readable one-liner.
acked: Whether the user has acknowledged it (feeds the header badge).
"""
ident: int
when: datetime
kind: str
label: str
message: str
acked: bool = False
@dataclass(slots=True)
class _State:
"""The store's in-memory shape (mirrors the JSON file)."""
watched: dict[str, WatchedNode] = field(default_factory=dict)
alerts: list[Alert] = field(default_factory=list)
known: set[str] = field(default_factory=set)
new_node_alerts: bool = True
next_id: int = 1
class WatchStore:
"""Reads and writes the Watchtower's state, memory-first."""
def __init__(self, path: Path) -> None:
"""Open the store against a JSON file location.
Args:
path: Path to the JSON state file (created lazily on first write).
"""
self._path = path
self._state: _State | None = None
self._dirty = False
self._last_flush = 0.0
# --- state ---------------------------------------------------------------------
@property
def state(self) -> _State:
"""The in-memory state, loaded from disk on first access."""
if self._state is None:
self._state = self._load()
return self._state
def _load(self) -> _State:
"""Parse the file into a :class:`_State`, or a fresh default on any trouble."""
try:
data = json.loads(self._path.read_text(encoding="utf-8"))
except (OSError, ValueError):
data = {}
if not isinstance(data, dict):
data = {}
state = _State(
new_node_alerts=bool(data.get("new_node_alerts", True)),
next_id=max(1, _as_int(data.get("next_id"), 1)),
known={str(k) for k in data.get("known", []) if isinstance(k, str)},
)
watched = data.get("watched")
if isinstance(watched, dict):
for key, record in watched.items():
if not isinstance(record, dict):
continue
raw_type = record.get("node_type")
state.watched[str(key)] = WatchedNode(
key=str(key),
name=str(record.get("name") or key),
silence_hours=_as_int(record.get("silence_hours"), DEFAULT_SILENCE_HOURS),
snr_watch=bool(record.get("snr_watch", True)),
last_heard=_as_time(record.get("last_heard")),
silent_since=_as_time(record.get("silent_since")),
node_type=raw_type if isinstance(raw_type, int) and raw_type >= 0 else None,
)
for record in data.get("alerts", []):
if not isinstance(record, dict):
continue
when = _as_time(record.get("when"))
if when is None:
continue
state.alerts.append(
Alert(
ident=_as_int(record.get("ident"), 0),
when=when,
kind=str(record.get("kind") or "alert"),
label=str(record.get("label") or "?"),
message=str(record.get("message") or ""),
acked=bool(record.get("acked", False)),
)
)
return state
# --- watched nodes ---------------------------------------------------------------
def watched(self) -> dict[str, WatchedNode]:
"""The watched nodes by canonical id (the live mapping — treat as read-mostly)."""
return self.state.watched
def is_watched(self, key: str) -> bool:
"""Whether ``key`` is on the watchlist."""
return key in self.state.watched
def watch(
self,
key: str,
name: str,
*,
last_seen: datetime | None = None,
node_type: int | None = None,
) -> None:
"""Star a node with default rules.
The silence countdown arms immediately: it counts from the contact's known
``last_seen`` when there is one (so a node that has already been quiet for a
day alarms on the next sweep, which is exactly why it was starred), else from
now.
Args:
key: The node's canonical 12-hex id.
name: Display label.
last_seen: When the node was last heard, if known.
node_type: The node's advertised type, if known (for the watchlist glyph).
"""
from .preferences import current as current_preferences
self.state.watched[key] = WatchedNode(
key=key,
name=name,
silence_hours=current_preferences().watch_silence_hours,
last_heard=last_seen or utcnow(),
node_type=node_type,
)
self._save()
def unwatch(self, key: str) -> None:
"""Drop a node from the watchlist (its past alerts stay in the log)."""
if self.state.watched.pop(key, None) is not None:
self._save()
def set_silence(self, key: str, hours: int) -> None:
"""Set a watched node's silence threshold (:data:`OFF` disables the rule)."""
entry = self.state.watched.get(key)
if entry is not None:
entry.silence_hours = int(hours)
self._save()
def set_snr_watch(self, key: str, on: bool) -> None:
"""Enable/disable the SNR-sag rule for a watched node."""
entry = self.state.watched.get(key)
if entry is not None:
entry.snr_watch = bool(on)
self._save()
def note_heard(
self, key: str, *, when: datetime | None = None, name: str | None = None
) -> None:
"""Record that a watched node was heard (packet-driven; writes throttled).
Args:
key: The node's canonical id.
when: Reception time (defaults to now); older-than-known stamps are kept.
name: A freshly advertised name, adopted as the display label when given.
"""
entry = self.state.watched.get(key)
if entry is None:
return
stamp = when or utcnow()
if entry.last_heard is None or stamp > entry.last_heard:
entry.last_heard = stamp
if name:
entry.name = name
self._dirty = True
self.flush(only_if_due=True)
def mark_silent(self, key: str, when: datetime | None = None) -> None:
"""Latch a node's active silence alarm so it fires once per quiet spell.
Packet/sweep-driven (like :meth:`note_heard`), so the write is throttled — the
full-state save is synchronous on the event loop, and the sentinel flushes any
pending change on stop.
"""
entry = self.state.watched.get(key)
if entry is not None:
entry.silent_since = when or utcnow()
self._dirty = True
self.flush(only_if_due=True)
def clear_silent(self, key: str) -> None:
"""Re-arm a node's silence alarm after it has been heard again.
Packet-driven, so throttled like :meth:`mark_silent` — a recovery burst after an
outage must not land one full-state disk write per packet.
"""
entry = self.state.watched.get(key)
if entry is not None and entry.silent_since is not None:
entry.silent_since = None
self._dirty = True
self.flush(only_if_due=True)
# --- the new-node baseline ---------------------------------------------------------
@property
def new_node_alerts(self) -> bool:
"""Whether hearing a never-before-seen node raises an alert."""
return self.state.new_node_alerts
def set_new_node_alerts(self, on: bool) -> None:
"""Toggle the new-node rule."""
self.state.new_node_alerts = bool(on)
self._save()
def known_contains(self, node: str) -> bool:
"""Whether ``node`` has already been recorded (never re-announced)."""
return node in self.state.known
def remember_known(self, node: str) -> None:
"""Record ``node`` as seen so it is announced as new at most once, ever."""
if node not in self.state.known:
self.state.known.add(node)
self._dirty = True
self.flush(only_if_due=True)
# --- alerts ---------------------------------------------------------------------
def add_alert(
self, kind: str, label: str, message: str, *, when: datetime | None = None
) -> Alert:
"""Append an alert to the log (capped) and persist, throttled.
Alerts fire from the packet path (a new mesh region can announce a never-seen
node per packet for a while), and the save serializes the whole state
synchronously on the event loop — so this batches through the same throttled
flush as :meth:`note_heard`. The in-memory log (and the header badge it feeds)
updates immediately either way; the sentinel flushes any pending write on stop.
Args:
kind: The rule that tripped (``silence``/``recovered``/``snr``/``new-node``).
label: The node's display label.
message: The human-readable one-liner.
when: When it tripped (defaults to now).
Returns:
The stored :class:`Alert`.
"""
state = self.state
alert = Alert(
ident=state.next_id,
when=when or utcnow(),
kind=kind,
label=label,
message=message,
)
state.next_id += 1
state.alerts.append(alert)
from .preferences import current as current_preferences
cap = current_preferences().watch_alerts_kept
if len(state.alerts) > cap:
del state.alerts[: len(state.alerts) - cap]
self._dirty = True
self.flush(only_if_due=True)
return alert
def alerts(self) -> list[Alert]:
"""The alert log, newest first (a copy, safe to slice)."""
return list(reversed(self.state.alerts))
def ack(self, ident: int) -> None:
"""Acknowledge one alert by id."""
for alert in self.state.alerts:
if alert.ident == ident and not alert.acked:
alert.acked = True
self._save()
return
def ack_all(self) -> None:
"""Acknowledge every alert."""
changed = False
for alert in self.state.alerts:
if not alert.acked:
alert.acked = True
changed = True
if changed:
self._save()
def clear_acked(self) -> None:
"""Drop acknowledged alerts from the log, keeping the live ones."""
state = self.state
kept = [a for a in state.alerts if not a.acked]
if len(kept) != len(state.alerts):
state.alerts = kept
self._save()
def unacked_count(self) -> int:
"""How many alerts are waiting — the header badge's number."""
return sum(1 for a in self.state.alerts if not a.acked)
# --- persistence -----------------------------------------------------------------
def flush(self, *, only_if_due: bool = False) -> None:
"""Write pending throttled changes to disk.
Args:
only_if_due: Skip when the last flush was recent (the packet-driven
path); a plain ``flush()`` writes any pending change immediately.
"""
if not self._dirty:
return
if only_if_due and time.monotonic() - self._last_flush < _FLUSH_EVERY_S:
return
self._save()
def _save(self) -> None:
"""Persist the whole state atomically (crash mid-write keeps the old file)."""
state = self.state
data = {
"new_node_alerts": state.new_node_alerts,
"next_id": state.next_id,
"known": sorted(state.known),
"watched": {
key: {
"name": e.name,
"silence_hours": e.silence_hours,
"snr_watch": e.snr_watch,
"last_heard": e.last_heard.isoformat() if e.last_heard else None,
"silent_since": e.silent_since.isoformat() if e.silent_since else None,
"node_type": e.node_type,
}
for key, e in state.watched.items()
},
"alerts": [
{
"ident": a.ident,
"when": a.when.isoformat(),
"kind": a.kind,
"label": a.label,
"message": a.message,
"acked": a.acked,
}
for a in state.alerts
],
}
self._path.parent.mkdir(parents=True, exist_ok=True)
tmp = self._path.with_suffix(self._path.suffix + ".tmp")
tmp.write_text(json.dumps(data, indent=2), encoding="utf-8")
tmp.replace(self._path)
self._dirty = False
self._last_flush = time.monotonic()
def _as_int(value: object, default: int) -> int:
"""Coerce a stored number to a non-negative int, falling back to ``default``."""
try:
number = int(value) # type: ignore[arg-type]
except (TypeError, ValueError):
return default
return number if number >= 0 else default
def _as_time(value: object) -> datetime | None:
"""Parse a stored ISO-8601 timestamp, or ``None`` if absent/corrupt.
A timestamp without a zone is treated as corrupt too: the store only ever writes
aware UTC stamps, and a naive one would poison the silence arithmetic.
"""
if not isinstance(value, str):
return None
try:
parsed = datetime.fromisoformat(value)
except ValueError:
return None
return parsed if parsed.tzinfo is not None else None