Files
MeshTerm/meshterm/core/advert_store.py
T
Jean-Pierre MartineauandClaude Opus 5.5 6a8efa2566 A retired name is never reused, and files keep only what the code knows
A value can outlive its key in a file nobody saved since; if the name came
back with a new meaning, an old value that passes the new spec would load
cleanly and mean something else. So every name that leaves is recorded as
retired: preference keys in preferences.RETIRED (the two old advert cadence
keys), stored fields in their record dataclass's own RETIRED set. A test
walks meshterm.core for such records and fails any live name found retired.

Loading preferences refuses retired keys and records every drop (retired,
unknown, invalid); report_dropped logs them once logging exists, INFO for a
retired key and WARNING naming a typo. adverts.json now reads into typed
records and writes out of them, so unknown fields die at the next write.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-23 22:00:13 -04:00

267 lines
11 KiB
Python

# SPDX-License-Identifier: Apache-2.0
"""Persistence for the weekly flood advert: when each device's week began.
A MeshCore companion never advertises by itself — no timer, not even at boot; only an app
asking (``CMD_SEND_SELF_ADVERT``) or a press on the device's own menu puts one on the air.
So a node that nobody remembers to advertise slowly drops out of everyone else's contact
list. The ``weekly_flood_advert`` preference is MeshTerm's answer, and deliberately a
frugal one: at most one flood advert a week from any one device, and only once that device
has gone a full week without one (see
:class:`~meshterm.services.advert_scheduler.AdvertScheduler`, which sends it).
This store remembers what that rule needs, and nothing else:
* **when the preference was turned on** — turning it on starts the week rather than
sending, so a week has to pass before the first automatic advert from any device;
* **per device** (keyed by its public key), **when its week began** — the last flood
advert that went out from it, whoever asked for it, or failing that the first time
MeshTerm connected to it.
A device's advert is due one week after the *latest* of those instants. The clock is real
time rather than run time, so a week with the app closed counts, and a due advert that the
app did not live to send is still due the next time that device connects.
Like the remembered devices (:mod:`meshterm.core.device_store`), this is global machine
state in a small JSON file (``<config_dir>/adverts.json``) rather than the per-invocation
SQLite database, read into typed records and written back out of them (see
:class:`AdvertStore`). A file in an older shape (the per-device cadences this replaced)
reads as empty: every device simply starts its week again.
"""
from __future__ import annotations
import json
from dataclasses import dataclass, field
from datetime import datetime, timedelta
from pathlib import Path
from typing import ClassVar
from .atomicwrite import write_atomically
from .models import utcnow
#: How long a device must go without a flood advert before the weekly one is due.
WEEK = timedelta(days=7)
#: The quiet spells the ``advert_quiet_s`` preference offers, in seconds: how long the air
#: must go without a packet, heard or sent, before the due advert goes out.
QUIET_CHOICES_S = (5, 15, 30, 60)
#: The quiet spell waited for by default, in seconds.
DEFAULT_QUIET_S = 30
@dataclass(slots=True)
class _Device:
"""One device's record: when its week began.
Attributes:
since: The last flood advert from it, or its first connection, whichever is
later — the instant its week counts from.
"""
since: datetime | None = None
#: Fields this record once held and must never hold again under another meaning (see
#: :data:`meshterm.core.preferences.RETIRED` for why a name is never reused).
RETIRED: ClassVar[frozenset[str]] = frozenset(
{
# The per-device cadences the weekly flood advert replaced.
"direct_hours",
"flood_hours",
"last_direct",
"last_flood",
}
)
@classmethod
def read(cls, raw: object) -> _Device:
"""Build a record from the file's JSON, taking only the fields it knows."""
record = raw if isinstance(raw, dict) else {}
return cls(since=_as_time(record.get("since")))
def to_json(self) -> dict:
"""The record as written: its own fields and nothing it happened to be read with."""
return {"since": _stamp(self.since)}
@dataclass(slots=True)
class _Document:
"""The whole file: the switch-on instant, and every device's record by public key.
Attributes:
enabled_since: When the weekly advert was last switched on; ``None`` while off.
devices: Each device's record, keyed by its normalized public key.
"""
enabled_since: datetime | None = None
devices: dict[str, _Device] = field(default_factory=dict)
#: Top-level fields this document once held; none yet (see :attr:`_Device.RETIRED`).
RETIRED: ClassVar[frozenset[str]] = frozenset()
@classmethod
def read(cls, raw: object) -> _Document:
"""Build the document from the file's JSON, taking only the fields it knows.
A file without a ``devices`` map is from before this shape — the per-device
cadences — and reads as empty rather than being mined for look-alike fields.
"""
if not isinstance(raw, dict) or not isinstance(raw.get("devices"), dict):
return cls()
return cls(
enabled_since=_as_time(raw.get("enabled_since")),
devices={str(k): _Device.read(v) for k, v in raw["devices"].items()},
)
def to_json(self) -> dict:
"""The document as written: known fields only, so a stale one dies at the next save."""
return {
"enabled_since": _stamp(self.enabled_since),
"devices": {key: device.to_json() for key, device in self.devices.items()},
}
class AdvertStore:
"""Reads and writes the weekly-advert clock: the switch-on instant, and each device's.
The file is read into typed records and written back out of them — never round-tripped
as the raw JSON it was read as — so a field no record knows (a retired one, one a hand
edit invented) is gone after the next write.
"""
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
@staticmethod
def _key(public_key: str) -> str:
"""Normalize a device public key into the storage key."""
return public_key.lower().removeprefix("0x")
def _load(self) -> _Document:
"""Read the file's document; an empty one when it is missing, corrupt or outdated."""
try:
raw = json.loads(self._path.read_text(encoding="utf-8"))
except (OSError, ValueError):
return _Document()
return _Document.read(raw)
def _write(self, document: _Document) -> None:
"""Persist ``document`` atomically (a crash mid-write keeps the previous file)."""
write_atomically(self._path, json.dumps(document.to_json(), indent=2))
# -- the switch ---------------------------------------------------------------------
def enabled_since(self) -> datetime | None:
"""When the weekly advert was last turned on, or ``None`` while it is off."""
return self._load().enabled_since
def set_enabled(self, on: bool, when: datetime | None = None) -> None:
"""Record the preference being turned on (starting the week) or off.
Turning it on always restarts the clock, even when it was already recorded as on:
the call means "it was switched on just now", and switching on never sends.
Args:
on: Whether the weekly advert is now on.
when: The switch-on instant (defaults to now); ignored when turning off.
"""
document = self._load()
if on:
document.enabled_since = when or utcnow()
elif document.enabled_since is not None:
document.enabled_since = None
else:
return # already off; nothing to write
self._write(document)
def sync_enabled(self, on: bool) -> None:
"""Bring the recorded switch into line with the preference, where they disagree.
The Preferences page and ``preferences set`` record the switch as it happens (see
:meth:`set_enabled`); this catches the one path neither sees, a hand edit of
``preferences.toml``, so a preference found on with no switch-on instant starts its
week now instead of never.
"""
recorded = self.enabled_since() is not None
if on != recorded:
self.set_enabled(on)
# -- the devices ----------------------------------------------------------------------
def week_began(self, public_key: str) -> datetime | None:
"""When a device's own week began, or ``None`` if MeshTerm has never marked it."""
device = self._load().devices.get(self._key(public_key))
return device.since if device is not None else None
def arm(self, public_key: str, when: datetime | None = None) -> None:
"""Start a device's week on its first connection, without sending anything.
Only writes for a device with no mark yet, so it is safe to call on every connect.
Args:
public_key: The device's public key (hex).
when: The week's start (defaults to now).
"""
if self.week_began(public_key) is None:
self.mark_flood(public_key, when=when)
def mark_flood(self, public_key: str, when: datetime | None = None) -> None:
"""Record a flood advert from a device, restarting its week.
Called for the weekly advert and for a flood advert sent by hand alike, so the
next automatic one is never less than a week after the last of either.
Args:
public_key: The device's public key (hex).
when: The send time (defaults to now).
"""
document = self._load()
document.devices[self._key(public_key)] = _Device(since=when or utcnow())
self._write(document)
# -- the verdict ----------------------------------------------------------------------
def due_at(self, public_key: str) -> datetime | None:
"""When a device's weekly advert falls due, or ``None`` while it cannot.
``None`` while the weekly advert is off, and for a device not yet armed.
Args:
public_key: The device's public key (hex).
"""
document = self._load()
device = document.devices.get(self._key(public_key))
if document.enabled_since is None or device is None or device.since is None:
return None
return max(document.enabled_since, device.since) + WEEK
def due(self, public_key: str, now: datetime | None = None) -> bool:
"""Whether a device's weekly advert is due at ``now`` (defaults to now)."""
at = self.due_at(public_key)
return at is not None and (now or utcnow()) >= at
def _stamp(when: datetime | None) -> str | None:
"""A timestamp as the file stores it: ISO-8601, or ``null`` for absent."""
return when.isoformat() if when is not None else None
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 ``due`` 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