Files
MeshTerm/meshterm/core/advert_store.py
T
Jean-Pierre MartineauandClaude Opus 5.5 ffe31dac36 Docstrings and comments of meshterm/core are in ASD-STE100
The prose of each docstring and comment in the core package now follows
ASD-STE100 Simplified Technical English, with Canadian spelling: short
sentences, simple verb tenses, no dashes or semicolons, and one word for
one concept (docs/development/writing-style.md has the rules and the
glossary). The meaning and each reason stay. The code does not change:
the AST of each file, without its docstrings, is the same as before.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-06 03:29:03 -04:00

289 lines
12 KiB
Python

# SPDX-License-Identifier: Apache-2.0
"""Storage for the weekly flood advert: the time when the week of each device started.
A MeshCore companion never sends an advert by itself. It has no timer, and it does not
send an advert at boot. Only a request from an app (``CMD_SEND_SELF_ADVERT``) or a press
on the menu of the device itself makes it transmit an advert. Thus, if nobody remembers to
send an advert for a node, that node slowly goes out of the contact lists of all the other
nodes. The ``weekly_flood_advert`` preference is the MeshTerm solution, and we made it
economical on purpose. It sends a maximum of one flood advert each week from one device,
and only after that device has had no flood advert for a full week (refer to
:class:`~meshterm.services.advert_scheduler.AdvertScheduler`, which sends it).
This store keeps the data that this rule must have, and no other data:
* **The time when the preference was turned on.** When the preference is turned on, the
week starts, but MeshTerm does not send an advert. Thus a week must pass before the
first automatic advert from a device.
* **For each device** (with its public key as the key), **the time when its week
started.** This is the time of the last flood advert from the device. It is not
important who asked for that advert. If there is no such advert, it is the first time
that MeshTerm connected to the device.
The advert of a device is due one week after the later of these two times. The clock is
real time, not run time. Thus a week in which the app is closed counts. Also, if an advert
is due and the app stops before it sends the advert, the advert is still due the next time
that the device connects.
This data is global state of the machine, the same as the remembered devices
(:mod:`meshterm.core.device_store`). It is in a small JSON file
(``<config_dir>/adverts.json``), not in the SQLite database of each invocation. The store
reads the file into typed records, and writes the file from these records (refer to
:class:`AdvertStore`). A file in an older shape (the per-device cadences that this store
replaced) is read as empty. Then each device 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
#: The time that a device must be without a flood advert before the weekly advert is due.
WEEK = timedelta(days=7)
#: The quiet periods that the ``advert_quiet_s`` preference offers, in seconds. A quiet
#: period is the time that the air must have no packet (heard or sent) before MeshTerm
#: sends the due advert.
QUIET_CHOICES_S = (5, 15, 30, 60)
#: The default quiet period, in seconds.
DEFAULT_QUIET_S = 30
@dataclass(slots=True)
class _Device:
"""The record of one device: the time when its week started.
Attributes:
since: The time of the last flood advert from the device, or of its first
connection, whichever is later. The week of the device starts at this time.
"""
since: datetime | None = None
#: Fields that this record held before. The record must never hold them again with a
#: different meaning (refer to :data:`meshterm.core.preferences.RETIRED` for the
#: reason that a name is never used again).
RETIRED: ClassVar[frozenset[str]] = frozenset(
{
# The per-device cadences that 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 JSON of the file, with only the fields that 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 the store writes it: its own fields, and no other field it read."""
return {"since": _stamp(self.since)}
@dataclass(slots=True)
class _Document:
"""The full file: the switch-on time, and the record of each device by public key.
Attributes:
enabled_since: The time when the weekly advert was last switched on. ``None``
while it is off.
devices: The record of each device, with its normalized public key as the key.
"""
enabled_since: datetime | None = None
devices: dict[str, _Device] = field(default_factory=dict)
#: Top-level fields that this document held before. There are none yet (refer to
#: :attr:`_Device.RETIRED`).
RETIRED: ClassVar[frozenset[str]] = frozenset()
@classmethod
def read(cls, raw: object) -> _Document:
"""Build the document from the JSON of the file, with only the fields that it knows.
A file without a ``devices`` map is from before this shape (the per-device
cadences). The method reads it as empty. It does not search the file for fields
that look the same.
"""
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 the store writes it: only the known fields.
Thus an old field that the store does not know is removed at the next write.
"""
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 clock of the weekly advert: the switch-on time, and each device's.
The store reads the file into typed records, and writes the file from these records.
It never writes back the raw JSON that it read. Thus a field that no record knows (a
retired field, or a field that a hand edit added) is removed at the next write.
"""
def __init__(self, path: Path) -> None:
"""Open the store on the location of a JSON file.
Args:
path: The path to the JSON state file. The store makes the file at the first
write.
"""
self._path = path
@staticmethod
def _key(public_key: str) -> str:
"""Normalize the public key of a device to the storage key."""
return public_key.lower().removeprefix("0x")
def _load(self) -> _Document:
"""Read the document of the file, or an empty one if the file is bad or missing.
A bad file is a corrupt file, or a file in an old shape.
"""
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:
"""Write ``document`` atomically (after a crash during the write, the old file stays)."""
write_atomically(self._path, json.dumps(document.to_json(), indent=2))
# -- the switch ---------------------------------------------------------------------
def enabled_since(self) -> datetime | None:
"""The time 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:
"""Store that the preference is turned on (this starts the week) or off.
When the preference is turned on, the clock always starts again, also when the
store already has it as on. The call means "it was switched on just now". A
switch-on never sends an advert.
Args:
on: Whether the weekly advert is now on.
when: The switch-on time (the default is now). The method ignores it when the
preference is turned 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, thus nothing to write
self._write(document)
def sync_enabled(self, on: bool) -> None:
"""Make the stored switch agree with the preference, if they are different.
The Preferences page and ``preferences set`` store the switch when it changes
(refer to :meth:`set_enabled`). This method catches the one path that these two do
not see: a hand edit of ``preferences.toml``. Thus, if the preference is on and has
no switch-on time, its week starts now, not 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:
"""The time when the week of a device started, or ``None`` if MeshTerm 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 the week of a device at its first connection, and send nothing.
The method writes only for a device that has no mark yet. Thus it is safe to call
it at each connection.
Args:
public_key: The public key of the device (hex).
when: The start of the week (the default is 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:
"""Store a flood advert from a device, and start its week again.
MeshTerm calls this method for the weekly advert, and also for a flood advert that
the user sends by hand. Thus the next automatic advert is never less than a week
after the last advert of either type.
Args:
public_key: The public key of the device (hex).
when: The send time (the default is 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:
"""The time when the weekly advert of a device is due, or ``None`` while it cannot be.
The value is ``None`` while the weekly advert is off, and for a device that is not
armed yet.
Args:
public_key: The public key of the device (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 the weekly advert of a device is due at ``now`` (the default is 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`` if there is no time."""
return when.isoformat() if when is not None else None
def _as_time(value: object) -> datetime | None:
"""Parse a stored ISO-8601 timestamp, or return ``None`` if it is absent or corrupt.
The function also treats a timestamp without a time zone as corrupt. The store writes
only aware UTC timestamps, and a naive timestamp makes the ``due`` arithmetic wrong.
"""
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