Files
MeshTerm/meshterm/core/channel_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

264 lines
11 KiB
Python

# SPDX-License-Identifier: Apache-2.0
"""The store for the channels that MeshTerm made, for a device that forgets them.
Most companions keep their own channel table in firmware. Thus MeshTerm reads the channels live
from the device, and does not have to remember them. A radio bridge without firmware is the
exception. It keeps its channels only in RAM, so it loses all of them when the bridge process
restarts. Then the Channels page is empty in each session, although you added channels in the
last session.
This store is the durable backup for exactly that case. It stores each channel that was written
through MeshTerm. (The channel manager and the ``channels`` CLI both go through
:func:`~meshterm.ui.channels.write_channel`.) The key is the public key of the device itself, so
that two devices keep separate sets. At connect time, :func:`reconcile` replays each remembered
channel that the device does not report now into a free slot. It fills gaps, and it never
overwrites a slot that is in use.
The gate is the origin of a channel, not the device type. The store keeps only the channels that
you wrote through MeshTerm. Thus a device with firmware that you never edit through MeshTerm
keeps an empty record, and MeshTerm does not change it at all. (When nothing is remembered,
``reconcile`` does a single identity probe and returns.) A radio bridge without firmware gets its
full set back, because each of its channels was necessarily made through MeshTerm.
This store is global machine state in a small JSON file (``<config_dir>/channels.json``), the
same as the other state of the user (mutes, watched nodes, admin passwords). It is not in the
SQLite database, which can be different for each run. After the first read, the store gives all
reads from memory. The writes are rare and come from the user. Each write goes to disk
immediately and atomically.
"""
from __future__ import annotations
import json
from dataclasses import dataclass
from pathlib import Path
from typing import TYPE_CHECKING, ClassVar
from .atomicwrite import write_atomically
from .channels import (
CHANNEL_SECRET_BYTES,
CHANNEL_SLOT_EMPTY_RUN,
CHANNEL_SLOT_PROBE_CAP,
MAX_CHANNELS,
channel_identity,
)
if TYPE_CHECKING:
from .connection import Device
@dataclass(frozen=True)
class RememberedChannel:
"""One channel that MeshTerm remembers for a device: its slot, name, and 16-byte secret."""
idx: int
name: str
secret: bytes
#: 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()
@property
def identity(self) -> str:
"""The intrinsic identity of the channel, which does not depend on the slot.
Refer to :func:`channel_identity`.
"""
return channel_identity(self.name, self.secret)
def _norm(pubkey: str) -> str:
"""Normalize the public key of a device to lowercase hex, the device key of the store."""
return (pubkey or "").lower().removeprefix("0x")
class ChannelStore:
"""Reads and writes the set of MeshTerm-managed channels for each device, in memory first.
Use :meth:`channels` (the remembered channels of a device), :meth:`remember` (store a
channel that was written to a slot), and :meth:`forget` (a cleared slot). The store reads
the map one time at the first access, and keeps it in memory. Each change writes the full
map atomically.
"""
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 when the first channel is
remembered).
"""
self._path = path
self._devices: dict[str, list[RememberedChannel]] | None = None
@property
def _state(self) -> dict[str, list[RememberedChannel]]:
"""The map from device to remembered channels, read from disk at the first access."""
if self._devices is None:
self._devices = self._load()
return self._devices
def _load(self) -> dict[str, list[RememberedChannel]]:
"""Parse the file into the device map (empty if 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 {}
devices: dict[str, list[RememberedChannel]] = {}
for pubkey, entries in (data.get("devices") or {}).items():
if not isinstance(entries, list):
continue
channels: list[RememberedChannel] = []
for entry in entries:
channel = _channel_from_json(entry)
if channel is not None:
channels.append(channel)
devices[_norm(str(pubkey))] = channels
return devices
def channels(self, pubkey: str) -> list[RememberedChannel]:
"""The remembered channels of a device (a copy, in slot order), empty if there are none."""
return sorted(self._state.get(_norm(pubkey), []), key=lambda c: c.idx)
def remember(self, pubkey: str, idx: int, name: str, secret: bytes) -> None:
"""Store the channel that is now in a slot, and replace the earlier entry for that slot.
MeshTerm calls this function after it writes a channel to the device. If the slot
already holds an identical channel, the function does nothing (no unnecessary write).
Args:
pubkey: The public key of the device itself.
idx: The slot to which the channel was written.
name: The channel name.
secret: The effective 16-byte secret of the channel. For a channel whose key
comes from its name, the store keeps the derived key. Thus MeshTerm can
replay the channel without a new derivation.
"""
key = _norm(pubkey)
if not key:
return
channels = list(self._state.get(key, []))
new = RememberedChannel(idx=idx, name=name, secret=bytes(secret))
existing = next((c for c in channels if c.idx == idx), None)
if existing == new:
return
channels = [c for c in channels if c.idx != idx]
channels.append(new)
self._state[key] = channels
self._save()
def forget(self, pubkey: str, idx: int) -> None:
"""Remove the remembered channel of a cleared slot.
Write the file only for a real change.
"""
key = _norm(pubkey)
channels = self._state.get(key)
if not channels or not any(c.idx == idx for c in channels):
return
self._state[key] = [c for c in channels if c.idx != idx]
self._save()
def _save(self) -> None:
"""Write the full device map atomically.
If a crash occurs during the write, the old file stays.
"""
data = {
"devices": {
pubkey: [
{"idx": c.idx, "name": c.name, "secret": c.secret.hex()}
for c in sorted(channels, key=lambda c: c.idx)
]
for pubkey, channels in sorted(self._state.items())
if channels
}
}
write_atomically(self._path, json.dumps(data, indent=2))
def _channel_from_json(entry: object) -> RememberedChannel | None:
"""Parse one stored channel entry, or return ``None`` if it is malformed."""
if not isinstance(entry, dict):
return None
try:
idx = int(entry["idx"])
name = str(entry["name"])
secret = bytes.fromhex(str(entry["secret"]))
except (KeyError, ValueError, TypeError):
return None
if not name or len(secret) != CHANNEL_SECRET_BYTES:
return None
return RememberedChannel(idx=idx, name=name, secret=secret)
async def reconcile(store: ChannelStore, device: Device) -> int:
"""Replay the remembered channels of a device into the slots that it does not report now.
The function restores each remembered channel that the device does not have. It compares
the channels by intrinsic identity, so a channel that moved to a different slot still
counts as present. The channel goes into its remembered slot when that slot is free, else
into the lowest free slot. The function never overwrites a slot that is in use. Thus a
device with firmware that kept its own channels stays as it is.
The function reads little, by design. When nothing is remembered for this device, it does
a single identity probe and returns. Thus a device with firmware that you do not manage
through MeshTerm pays almost nothing. The function is best-effort. The caller runs it at
connect time, and must not let a failure here break the connection.
Args:
store: The channel store from which to read the remembered channels.
device: The device that connected a moment ago, to reconcile.
Returns:
The number of channels that were restored (0 when no replay was necessary).
"""
info = await device.get_self_info()
remembered = store.channels(info.get("public_key", ""))
if not remembered:
return 0
used: set[int] = set()
present_ids: set[str] = set()
empty_run = 0
for idx in range(CHANNEL_SLOT_PROBE_CAP):
try:
payload = await device.get_channel(idx)
except Exception: # noqa: BLE001 - firmware may reject an out-of-range index
break
if payload and payload.get("channel_name"):
empty_run = 0
used.add(idx)
name = str(payload["channel_name"])
secret = bytes(payload.get("channel_secret") or b"\x00" * CHANNEL_SECRET_BYTES)
present_ids.add(channel_identity(name, secret))
else:
empty_run += 1
if empty_run >= CHANNEL_SLOT_EMPTY_RUN:
break # past the end, on a firmware that never refuses. No more channels.
restored = 0
for channel in remembered:
if channel.identity in present_ids:
continue # already on the device (maybe in another slot). Do not change it.
target = channel.idx if channel.idx not in used else _next_free_slot(used)
if target is None:
break # each slot is full. Nothing more can be restored.
await device.set_channel(target, channel.name, channel.secret)
used.add(target)
present_ids.add(channel.identity)
restored += 1
return restored
def _next_free_slot(used: set[int]) -> int | None:
"""The lowest slot index that is not in ``used``, in the stock capacity.
The function returns ``None`` if all the slots are full.
"""
return next((i for i in range(MAX_CHANNELS) if i not in used), None)