Files
MeshTerm/meshterm/core/channel_store.py
T
Jean-Pierre MartineauandClaude Opus 4.8 711621d69e Channels: remember MeshTerm-created channels across sessions
A firmware-less radio bridge holds its channels only in RAM, so every one is
lost when the bridge restarts — the Channels page came up empty each session
even after you added channels. MeshTerm read channels live from the device and
never remembered them.

Add a durable, per-device channel store (<config_dir>/channels.json, keyed by
the device's public key) that records every channel written through MeshTerm.
On connect, reconcile() replays any remembered channel the device isn't
reporting into a free slot — filling gaps, never overwriting an occupied slot.

The gate is provenance, not device type: only channels you wrote through
MeshTerm are recorded, so a firmware radio you never edit through MeshTerm keeps
an empty record and does a single identity probe on connect (untouched). A
bridge, where every channel is necessarily created through MeshTerm, gets its
whole set back. Every mutation (create/join/import/edit/reorder/clear) now flows
through a single write_channel() boundary that keeps the store faithful.

Verified end to end against the live SPI bridge: write a channel, clear it off
the device to mimic a restart, reconnect in a fresh session, and reconcile
restores it with the right key.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-24 18:20:49 -04:00

240 lines
9.8 KiB
Python

"""Persistence for channels created through MeshTerm, so they survive a device that forgets.
Most companions keep their own channel table in firmware, so MeshTerm reads channels live from
the device and never has to remember them. A firmware-less radio bridge is the exception: it
holds its channels only in RAM, so every one is lost when the bridge process restarts — the
Channels page comes up empty each session even though you added channels last time.
This store is the durable backup for exactly that case. It records every channel *written
through MeshTerm* (the channel manager and the ``channels`` CLI both go through
:func:`~meshterm.ui.channels.write_channel`), keyed by the device's own public key so two radios
keep separate sets. On connect, :func:`reconcile` replays any remembered channel the device
isn't currently reporting into a free slot — *filling gaps, never overwriting an occupied slot*.
The gate is provenance, not device type: only channels you wrote through MeshTerm are recorded,
so a firmware radio you never edit through MeshTerm keeps an empty record and is left completely
untouched (with nothing remembered, ``reconcile`` does a single identity probe and returns). A
firmware-less bridge, where every channel is necessarily created through MeshTerm, gets its
whole set back.
Like the operator preferences (mutes, watched nodes, admin passwords), this is global machine
state in a small JSON file (``<config_dir>/channels.json``), not the per-invocation SQLite
database. Reads are served from memory after the first load; the rare, user-driven writes flush
immediately and atomically.
"""
from __future__ import annotations
import json
from dataclasses import dataclass
from pathlib import Path
from typing import TYPE_CHECKING, Optional
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 MeshTerm remembers for a device: its slot, name, and 16-byte secret."""
idx: int
name: str
secret: bytes
@property
def identity(self) -> str:
"""The channel's slot-independent intrinsic identity (see :func:`channel_identity`)."""
return channel_identity(self.name, self.secret)
def _norm(pubkey: str) -> str:
"""Normalise a device public key to the lowercase hex used as the store's device key."""
return (pubkey or "").lower().removeprefix("0x")
class ChannelStore:
"""Reads and writes the per-device set of MeshTerm-managed channels, memory-first.
Interact through :meth:`channels` (a device's remembered channels), :meth:`remember` (record
a channel written to a slot), and :meth:`forget` (a cleared slot). The backing map is loaded
once on first access and kept in memory; each mutation persists the whole map atomically.
"""
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 the first remembered channel).
"""
self._path = path
self._devices: Optional[dict[str, list[RememberedChannel]]] = None
@property
def _state(self) -> dict[str, list[RememberedChannel]]:
"""The device -> remembered-channels map, loaded from disk on 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, or empty on a missing/corrupt file."""
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 channels remembered for a device (a copy, in slot order), empty if 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:
"""Record the channel now occupying a slot, replacing any prior entry for that slot.
Called after a channel is written to the device through MeshTerm. A slot already
holding an identical channel is a no-op (no needless write).
Args:
pubkey: The device's own public key.
idx: The slot the channel was written to.
name: The channel name.
secret: The channel's effective 16-byte secret (a name-derived channel stores the
derived key so it can be replayed without re-deriving).
"""
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:
"""Drop the channel remembered for a slot (a cleared slot); persist only 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:
"""Persist the whole device map atomically (a crash mid-write keeps the old file)."""
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
}
}
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)
def _channel_from_json(entry: object) -> Optional[RememberedChannel]:
"""Parse one stored channel entry, or ``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 a device's remembered channels into any slots it isn't already reporting.
Restores each remembered channel the device is missing (matched by intrinsic identity, so a
channel that moved slots still counts as present) into its remembered slot when free, else
the lowest free slot. An occupied slot is never overwritten, so a firmware radio that kept
its own channels is left as-is.
Read-cheap by design: with nothing remembered for this device it does a single identity
probe and returns, so a firmware radio you don't manage through MeshTerm pays almost nothing.
Best-effort — the caller runs it on connect and must not let a failure here break connecting.
Args:
store: The channel store to read remembered channels from.
device: The freshly connected device to reconcile.
Returns:
The number of channels restored (0 when nothing needed replaying).
"""
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 # off the end of a never-rejecting firmware; nothing more configured
restored = 0
for channel in remembered:
if channel.identity in present_ids:
continue # already on the device (possibly at another slot) — leave it be
target = channel.idx if channel.idx not in used else _next_free_slot(used)
if target is None:
break # every slot is full; nothing more we can restore
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]) -> Optional[int]:
"""The lowest slot index not in ``used`` within the stock capacity, or ``None`` if full."""
return next((i for i in range(MAX_CHANNELS) if i not in used), None)