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>
442 lines
19 KiB
Python
442 lines
19 KiB
Python
# SPDX-License-Identifier: Apache-2.0
|
|
"""The regions that MeshTerm knows by name, and the scope under which each channel sends.
|
|
|
|
A scoped flood has no region name. It has only a transport code that comes from a region
|
|
name (refer to :mod:`~meshterm.core.regions`). Thus, to find the region into which a
|
|
packet was flooded, MeshTerm must try the names that it knows. This store is that list.
|
|
MeshTerm learns a name from each place where it finds one:
|
|
|
|
* ``default``: the default flood scope of the companion, read or set on Device config.
|
|
* ``channel``: a scope that is given to a channel, so that its messages stay in its
|
|
region.
|
|
* ``repeater``: the answer of a repeater to the regions request, or its ``region``
|
|
listing. The store also keeps which repeaters carry the region. The node page lists
|
|
them. Also, when nothing relayed a scoped send, MeshTerm can tell whether a node in
|
|
radio range was ever heard to carry its region. Next to the regions, the store keeps
|
|
the last full answer of each repeater: whether it also relays unscoped floods, and
|
|
when it said so (:class:`CarriedAnswer`).
|
|
* ``typed``: a name that the user typed.
|
|
|
|
The store also keeps the **channel scopes**. A channel scope is the region under which
|
|
MeshTerm sends the messages of a channel. The firmware has no scope for each channel
|
|
(``// TODO: have per-channel send_scope``). Thus a client that wants one sets the session
|
|
scope of the companion immediately before each channel send. Each official app does
|
|
this. The key of a channel scope is the intrinsic identity of the channel
|
|
(:func:`~meshterm.core.channels.channel_identity`), the same as for a mute. Thus the
|
|
scope follows the channel to a different slot, and two devices that share the channel
|
|
also share its scope.
|
|
|
|
The store also caches the resolution (:meth:`RegionStore.scope_of`). A packet list paints
|
|
often, and the resolution of a scoped packet costs one HMAC for each known name. Thus the
|
|
store keeps an answer for each ``(body, code)`` until the set of names changes.
|
|
|
|
This store is global machine state in a small JSON file (``<config_dir>/regions.json``),
|
|
the same as the other state of the user (mutes, watched nodes, admin passwords). The
|
|
store reads the file one time, and writes it atomically at each real change. It writes
|
|
from its typed records, never from the document that it read. Thus a field that no
|
|
record knows is removed at the next save.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
from collections.abc import Iterable
|
|
from dataclasses import dataclass, field, replace
|
|
from datetime import datetime, timezone
|
|
from pathlib import Path
|
|
from typing import ClassVar
|
|
|
|
from .atomicwrite import write_atomically
|
|
from .regions import (
|
|
WILDCARD,
|
|
RegionNameError,
|
|
Scope,
|
|
frame_scope,
|
|
normalize,
|
|
raw_scope_body,
|
|
validate,
|
|
)
|
|
|
|
#: Where MeshTerm learned a region name. This is the closed set from which
|
|
#: :attr:`KnownRegion.sources` takes its values.
|
|
SOURCES = ("default", "channel", "repeater", "typed")
|
|
|
|
#: The maximum number of cached resolutions. At this number, the store clears the full
|
|
#: cache. (A long capture finds many bodies. A paint finds the same few hundred bodies
|
|
#: again and again.)
|
|
_MEMO_CAP = 4096
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class KnownRegion:
|
|
"""One region that MeshTerm knows by name.
|
|
|
|
Attributes:
|
|
name: The bare region name (no ``#``).
|
|
sources: Where MeshTerm learned it, as members of :data:`SOURCES`, in the order
|
|
in which they were first learned.
|
|
repeaters: The 12-hex node ids of the repeaters that were heard to carry it.
|
|
learned_at: When MeshTerm first learned it (UTC).
|
|
"""
|
|
|
|
name: str
|
|
sources: tuple[str, ...] = ()
|
|
repeaters: tuple[str, ...] = ()
|
|
learned_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
|
|
|
|
#: The fields that this record held before. It 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()
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class CarriedAnswer:
|
|
"""The last full answer of one repeater about what it carries.
|
|
|
|
The regions themselves are on :class:`KnownRegion` (``repeaters``), where the
|
|
resolution uses them. This record keeps what does not belong to one region: whether
|
|
the repeater also relays unscoped floods (the ``*`` at the start of a region list,
|
|
which names no region), and when it said so. If a repeater has no record here,
|
|
MeshTerm never asked it. That is different from a repeater that answered with no
|
|
regions.
|
|
|
|
Attributes:
|
|
node: The 12-hex node id of the repeater.
|
|
unscoped: Whether its answer included the wildcard.
|
|
answered_at: When it answered (UTC).
|
|
"""
|
|
|
|
node: str
|
|
unscoped: bool
|
|
answered_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
|
|
|
|
#: The fields that this record held before. It must never hold them again with a
|
|
#: different meaning.
|
|
RETIRED: ClassVar[frozenset[str]] = frozenset()
|
|
|
|
|
|
class RegionStore:
|
|
"""Reads and writes the known regions and the channel scopes, in memory first.
|
|
|
|
Use :meth:`names`/:meth:`regions` (what is known), :meth:`learn` and :meth:`forget`
|
|
(to change it), :meth:`channel_scope`/:meth:`set_channel_scope` (the send scope of a
|
|
channel), :meth:`carriers` (which repeaters carry a region), and :meth:`scope_of`
|
|
(the scope of a received packet). :attr:`revision` increases at each change, for a
|
|
screen that caches on it.
|
|
"""
|
|
|
|
def __init__(self, path: Path) -> None:
|
|
"""Open the store on the location of a JSON file.
|
|
|
|
Args:
|
|
path: Path to the JSON state file (made only at the first change).
|
|
"""
|
|
self._path = path
|
|
self._regions: dict[str, KnownRegion] | None = None
|
|
self._channels: dict[str, str] = {}
|
|
self._answers: dict[str, CarriedAnswer] = {}
|
|
self._memo: dict[tuple[bytes, int], str | None] = {}
|
|
self.revision = 0
|
|
|
|
# -- read from disk ----------------------------------------------------------------
|
|
|
|
@property
|
|
def _state(self) -> dict[str, KnownRegion]:
|
|
"""The map from name to record, read from disk at the first access."""
|
|
if self._regions is None:
|
|
self._regions, self._channels, self._answers = self._load()
|
|
return self._regions
|
|
|
|
def _load(
|
|
self,
|
|
) -> tuple[dict[str, KnownRegion], dict[str, str], dict[str, CarriedAnswer]]:
|
|
"""Parse the file, or start empty when the file is missing or corrupt."""
|
|
try:
|
|
data = json.loads(self._path.read_text(encoding="utf-8"))
|
|
except (OSError, ValueError):
|
|
return {}, {}, {}
|
|
if not isinstance(data, dict):
|
|
return {}, {}, {}
|
|
regions: dict[str, KnownRegion] = {}
|
|
for entry in data.get("regions") or []:
|
|
region = _region_from_json(entry)
|
|
if region is not None:
|
|
regions[region.name] = region
|
|
channels: dict[str, str] = {}
|
|
for identity, name in (data.get("channels") or {}).items():
|
|
try:
|
|
channels[str(identity)] = validate(str(name))
|
|
except RegionNameError:
|
|
continue
|
|
answers: dict[str, CarriedAnswer] = {}
|
|
for entry in data.get("answers") or []:
|
|
answer = _answer_from_json(entry)
|
|
if answer is not None:
|
|
answers[answer.node] = answer
|
|
return regions, channels, answers
|
|
|
|
# -- what is known ---------------------------------------------------------------
|
|
|
|
def regions(self) -> list[KnownRegion]:
|
|
"""All the known regions, in the order in which the names are tried for a packet.
|
|
|
|
The names that the user chose (a default scope, a channel scope, a typed name)
|
|
come first. Then come the names that only a repeater gave. The reason: the names
|
|
under which our node most probably sends are the names that its own packets will
|
|
carry. Names in the same group keep the order in which they were learned.
|
|
"""
|
|
chosen = [r for r in self._state.values() if set(r.sources) - {"repeater"}]
|
|
heard = [r for r in self._state.values() if not set(r.sources) - {"repeater"}]
|
|
return chosen + heard
|
|
|
|
def names(self) -> list[str]:
|
|
"""The known region names, in resolution order (refer to :meth:`regions`)."""
|
|
return [r.name for r in self.regions()]
|
|
|
|
def get(self, name: str) -> KnownRegion | None:
|
|
"""The record for one region name, or ``None`` if it is not known."""
|
|
return self._state.get(normalize(name))
|
|
|
|
def carriers(self, name: str) -> tuple[str, ...]:
|
|
"""The node ids of the repeaters that were heard to carry a region (or empty)."""
|
|
region = self.get(name)
|
|
return region.repeaters if region else ()
|
|
|
|
def carried_by(self, node: str) -> list[str]:
|
|
"""The regions that a repeater was heard to carry, by its node id (12-hex key prefix)."""
|
|
node = node.lower()[:12]
|
|
return [r.name for r in self.regions() if node in r.repeaters]
|
|
|
|
def answer_of(self, node: str) -> CarriedAnswer | None:
|
|
"""The last full answer of a repeater (its unscoped flag and its time), or ``None``.
|
|
|
|
``None`` means that MeshTerm never asked the repeater, or that it never answered.
|
|
The node page shows this case as it is. It does not read an empty
|
|
:meth:`carried_by` as "carries nothing".
|
|
"""
|
|
self._state # noqa: B018 - load on first access
|
|
return self._answers.get(node.lower()[:12])
|
|
|
|
# -- change it -------------------------------------------------------------------
|
|
|
|
def learn(self, name: str, source: str, *, repeater: str | None = None) -> str | None:
|
|
"""Store a region name and its source. Write the file only for a real change.
|
|
|
|
Args:
|
|
name: The name, bare or with a ``#`` prefix. The function ignores the wildcard
|
|
and the names that the firmware refuses (a repeater that lists ``*``
|
|
teaches no region).
|
|
source: One of :data:`SOURCES`.
|
|
repeater: For ``source="repeater"``, the node id of the repeater that carries
|
|
the region.
|
|
|
|
Returns:
|
|
The bare name that was stored, or ``None`` when there was nothing to learn.
|
|
"""
|
|
if source not in SOURCES:
|
|
raise ValueError(f"unknown region source {source!r}")
|
|
try:
|
|
bare = validate(name)
|
|
except RegionNameError:
|
|
return None
|
|
current = self._state.get(bare) or KnownRegion(name=bare)
|
|
sources = current.sources if source in current.sources else current.sources + (source,)
|
|
repeaters = current.repeaters
|
|
if repeater:
|
|
node = repeater.lower()[:12]
|
|
if node not in repeaters:
|
|
repeaters = repeaters + (node,)
|
|
updated = replace(current, sources=sources, repeaters=repeaters)
|
|
if self._state.get(bare) != updated:
|
|
self._state[bare] = updated
|
|
self._changed()
|
|
return bare
|
|
|
|
def learn_carried(self, repeater: str, names: Iterable[str]) -> list[str]:
|
|
"""Store what one repeater says that it carries, and replace what it said before.
|
|
|
|
The list of a repeater is its full answer. Thus a region that the repeater no
|
|
longer names loses that repeater. If nothing else taught the region, the store
|
|
also removes the region itself. Next to the regions, the store keeps whether the
|
|
repeater listed the wildcard (that is, it relays unscoped floods), and when it
|
|
answered (:meth:`answer_of`).
|
|
|
|
Args:
|
|
repeater: The node id of the repeater (a 12-hex key prefix or the full key).
|
|
names: The regions that it listed (the store keeps the wildcard as the
|
|
unscoped flag).
|
|
|
|
Returns:
|
|
The bare region names that were learned, in the given order.
|
|
"""
|
|
node = repeater.lower()[:12]
|
|
given = [normalize(x) for x in names]
|
|
self._state # noqa: B018 - load on first access
|
|
self._answers[node] = CarriedAnswer(node=node, unscoped=WILDCARD in given)
|
|
self._changed()
|
|
wanted = [n for n in given if n and n != WILDCARD]
|
|
learned: list[str] = []
|
|
for name in wanted:
|
|
bare = self.learn(name, "repeater", repeater=node)
|
|
if bare:
|
|
learned.append(bare)
|
|
for region in list(self._state.values()):
|
|
if node in region.repeaters and region.name not in learned:
|
|
repeaters = tuple(r for r in region.repeaters if r != node)
|
|
sources = region.sources
|
|
if not repeaters:
|
|
sources = tuple(s for s in sources if s != "repeater")
|
|
if not sources:
|
|
del self._state[region.name]
|
|
else:
|
|
self._state[region.name] = replace(region, sources=sources, repeaters=repeaters)
|
|
self._changed()
|
|
return learned
|
|
|
|
def forget(self, name: str) -> None:
|
|
"""Remove a region name completely, and each channel scope that used it."""
|
|
bare = normalize(name)
|
|
if bare not in self._state and bare not in self._channels.values():
|
|
return
|
|
self._state.pop(bare, None)
|
|
self._channels = {k: v for k, v in self._channels.items() if v != bare}
|
|
self._changed()
|
|
|
|
# -- channel scopes ----------------------------------------------------------------
|
|
|
|
def channel_scope(self, channel_id: str | None) -> str | None:
|
|
"""The send scope of a channel, or ``None`` for the default scope.
|
|
|
|
The send scope is the region under which MeshTerm sends the messages of the channel.
|
|
"""
|
|
self._state # noqa: B018 - load on first access
|
|
return self._channels.get(channel_id) if channel_id else None
|
|
|
|
def channel_scopes(self) -> dict[str, str]:
|
|
"""All the channel scopes, as channel identity -> region (a copy)."""
|
|
self._state # noqa: B018 - load on first access
|
|
return dict(self._channels)
|
|
|
|
def set_channel_scope(self, channel_id: str, name: str | None) -> None:
|
|
"""Give a channel a send scope, or clear it to use the default of the device again.
|
|
|
|
Args:
|
|
channel_id: The intrinsic identity of the channel.
|
|
name: The region, or ``None``/empty to clear the scope.
|
|
|
|
Raises:
|
|
RegionNameError: If ``name`` is a name that the firmware refuses.
|
|
"""
|
|
self._state # noqa: B018 - load on first access
|
|
if not name or not normalize(name):
|
|
if self._channels.pop(channel_id, None) is not None:
|
|
self._changed()
|
|
return
|
|
bare = validate(name)
|
|
self.learn(bare, "channel")
|
|
if self._channels.get(channel_id) != bare:
|
|
self._channels[channel_id] = bare
|
|
self._changed()
|
|
|
|
# -- resolution ------------------------------------------------------------------
|
|
|
|
def scope_of(self, raw: dict | None) -> Scope | None:
|
|
"""The scope of a received packet, resolved against each known name (cached).
|
|
|
|
Args:
|
|
raw: The raw payload of the packet (live, or restored from the history).
|
|
|
|
Returns:
|
|
The same as :func:`~meshterm.core.regions.frame_scope`: ``None`` where the
|
|
packet has no scope to show (a direct packet, or a route type that was never
|
|
kept).
|
|
"""
|
|
if not isinstance(raw, dict):
|
|
return None
|
|
route = str(raw.get("route_typename") or "").upper()
|
|
if route != "TC_FLOOD":
|
|
return frame_scope(raw, ())
|
|
body = raw_scope_body(raw)
|
|
scope = frame_scope(raw, ()) # parses the code only. The resolution comes below.
|
|
if scope is None or scope.code is None or body is None:
|
|
return scope
|
|
memo_key = (body, int(scope.code, 16))
|
|
if memo_key not in self._memo:
|
|
if len(self._memo) >= _MEMO_CAP:
|
|
self._memo.clear()
|
|
self._memo[memo_key] = (frame_scope(raw, self.names()) or scope).region
|
|
region = self._memo[memo_key]
|
|
return Scope("scoped", region, scope.code) if region else scope
|
|
|
|
# -- write to disk ---------------------------------------------------------------
|
|
|
|
def _changed(self) -> None:
|
|
"""Increase the revision, clear the cache, and write the file."""
|
|
self.revision += 1
|
|
self._memo.clear()
|
|
self._save()
|
|
|
|
def _save(self) -> None:
|
|
"""Write the full store atomically.
|
|
|
|
If a crash occurs during the write, the old file stays.
|
|
"""
|
|
data = {
|
|
"regions": [
|
|
{
|
|
"name": r.name,
|
|
"sources": list(r.sources),
|
|
"repeaters": list(r.repeaters),
|
|
"learned_at": r.learned_at.astimezone(timezone.utc).isoformat(),
|
|
}
|
|
for r in self._state.values()
|
|
],
|
|
"channels": dict(sorted(self._channels.items())),
|
|
"answers": [
|
|
{
|
|
"node": a.node,
|
|
"unscoped": a.unscoped,
|
|
"answered_at": a.answered_at.astimezone(timezone.utc).isoformat(),
|
|
}
|
|
for a in self._answers.values()
|
|
],
|
|
}
|
|
write_atomically(self._path, json.dumps(data, indent=2, ensure_ascii=False))
|
|
|
|
|
|
def _answer_from_json(entry: object) -> CarriedAnswer | None:
|
|
"""Parse one stored answer of a repeater, or return ``None`` if it is malformed."""
|
|
if not isinstance(entry, dict) or not entry.get("node"):
|
|
return None
|
|
try:
|
|
answered_at = datetime.fromisoformat(str(entry["answered_at"]))
|
|
except (KeyError, ValueError):
|
|
return None
|
|
if answered_at.tzinfo is None:
|
|
answered_at = answered_at.replace(tzinfo=timezone.utc)
|
|
return CarriedAnswer(
|
|
node=str(entry["node"]).lower()[:12],
|
|
unscoped=bool(entry.get("unscoped")),
|
|
answered_at=answered_at,
|
|
)
|
|
|
|
|
|
def _region_from_json(entry: object) -> KnownRegion | None:
|
|
"""Parse one stored region, or return ``None`` if it is malformed."""
|
|
if not isinstance(entry, dict):
|
|
return None
|
|
try:
|
|
name = validate(str(entry["name"]))
|
|
except (KeyError, RegionNameError):
|
|
return None
|
|
sources = tuple(s for s in entry.get("sources") or () if s in SOURCES)
|
|
repeaters = tuple(str(r).lower()[:12] for r in entry.get("repeaters") or () if r)
|
|
try:
|
|
learned_at = datetime.fromisoformat(str(entry["learned_at"]))
|
|
except (KeyError, ValueError):
|
|
learned_at = datetime.now(timezone.utc)
|
|
if learned_at.tzinfo is None:
|
|
learned_at = learned_at.replace(tzinfo=timezone.utc)
|
|
return KnownRegion(name=name, sources=sources, repeaters=repeaters, learned_at=learned_at)
|