From 3c38b366cfba64ad6495f2f9b9829d4d563e5db3 Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Fri, 24 Jul 2026 21:22:34 -0400 Subject: [PATCH] Contacts: purge stale contacts by how long since last heard MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a "πŸ—‘ Purge stale contacts…" action at the foot of the Contacts list. It offers an age ladder (1 week β†’ 1 year, plus a never-heard bucket), each rung showing a live count of how many contacts it would sweep, so the impact is visible before choosing; the pick is gated behind a typed "delete" confirm. A purge deletes each contact from the device table (new Device.remove_contact, over the meshcore remove_contact command) and forgets it from the cross-session contact store so a firmware-less bridge doesn't merge it back β€” but only the contact is dropped: each node's reception history in MeshTerm is untouched, and our own pinned node is never a candidate. The contacts cache is invalidated and the list rebuilt so swept contacts are gone from it. ContactListScreen gains a `tail` param (symmetric to `lead`) for the action and Back rows; age bucketing (stale_past / never_heard) is factored out pure and tested, alongside MockDevice.remove_contact and the screen's tail composition. Co-Authored-By: Claude Opus 4.8 (1M context) --- meshterm/core/connection.py | 27 +++++ meshterm/ui/contactlist.py | 13 ++- meshterm/ui/contacts_screen.py | 207 ++++++++++++++++++++++++++++++++- tests/test_device_config.py | 47 +++++++- tests/test_skeleton.py | 15 +++ 5 files changed, 300 insertions(+), 9 deletions(-) diff --git a/meshterm/core/connection.py b/meshterm/core/connection.py index 05285a6..32c37b6 100644 --- a/meshterm/core/connection.py +++ b/meshterm/core/connection.py @@ -361,6 +361,23 @@ class Device(ABC): The list of :class:`Contact` records currently stored on the device. """ + @abstractmethod + async def remove_contact(self, node: Contact) -> None: + """Delete a contact from the device's contact table. + + Addresses the contact by its public key, so it must carry one (a contact heard + as an advert always does). The node stays a *node* β€” its reception history and any + overheard traffic are untouched β€” it is only dropped from the device's list of + added, messageable contacts. + + Args: + node: The contact to remove. + + Raises: + DeviceCommandError: If the contact carries no public key to address it by, or + the device rejected the removal. + """ + @abstractmethod async def get_tx_power(self) -> Optional[int]: """Return the current TX power level, or ``None`` if unknown.""" @@ -1420,6 +1437,11 @@ class MeshCoreDevice(Device): ) return contacts + async def remove_contact(self, node: Contact) -> None: # noqa: D102 - inherited docstring + mc = self._require() + pub = self._node_pubkey(node) # raises DeviceCommandError if it has no key + self._ok(await mc.commands.remove_contact(pub)) + async def get_tx_power(self) -> Optional[int]: # noqa: D102 - inherited docstring info = await self.get_self_info() value = info.get("tx_power") @@ -2199,6 +2221,11 @@ class MockDevice(Device): async def get_contacts(self) -> list[Contact]: # noqa: D102 - inherited docstring return list(self._contacts) + async def remove_contact(self, node: Contact) -> None: # noqa: D102 - inherited docstring + await asyncio.sleep(0) + key = self._mock_key(node) + self._contacts = [c for c in self._contacts if self._mock_key(c) != key] + async def get_tx_power(self) -> Optional[int]: # noqa: D102 - inherited docstring return self._tx_power diff --git a/meshterm/ui/contactlist.py b/meshterm/ui/contactlist.py index 8dc0591..c9af6b3 100644 --- a/meshterm/ui/contactlist.py +++ b/meshterm/ui/contactlist.py @@ -351,6 +351,7 @@ class ContactListScreen(SelectScreen): sort: ContactsSort, prompt: str = "", lead: Optional[list] = None, + tail: Optional[list] = None, footer_hint: str = _HINT, show_traced: bool = False, ) -> None: @@ -368,6 +369,11 @@ class ContactListScreen(SelectScreen): prompt: An optional instruction shown above the list. lead: Rows (choices/separators) drawn above the column header β€” the Time Machine's whole-mesh row and its section heading; ``None`` for none. + tail: Rows (choices/separators) drawn *below* the sorted contacts β€” the + Contacts screen's ``Purge stale contacts…`` action and its ``Back`` exit + group. They sit past every contact whatever the sort, and (being ordinary + choices) fall out of view while a type-to-filter narrows the list, exactly + like the Trophy case's delete rows. ``None`` for a pure pick-list. footer_hint: Footer key hint; the default advertises the full grammar. show_traced: Whether to draw the ``TRACED`` lane (last-traced age) between the name and heard lanes β€” the Trace-target picker only. Pair it with a ``sort`` @@ -378,6 +384,7 @@ class ContactListScreen(SelectScreen): self._sort = sort self._show_traced = show_traced self._lead = list(lead) if lead else [] + self._tail = list(tail) if tail else [] # Provisional until the first render learns the true width (see render_body). self._name_w = _NAME_MIN self._hash_w = _HASH_MIN @@ -390,10 +397,11 @@ class ContactListScreen(SelectScreen): ) def _compose_items(self) -> list: - """The lead rows, the sort-aware column header, then the contact lanes. + """The lead rows, the sort-aware column header, the contact lanes, then any tail rows. Own-node rows lead the lanes and stay first whatever the sort: only the block - below them reorders (see :func:`_ordered`).""" + below them reorders (see :func:`_ordered`). Tail rows (a purge action, the exit + group) close the list, past every contact whatever the sort.""" items: list = list(self._lead) items.append(Separator(_header(self._name_w, self._sort, self._show_traced))) pinned = [row for row in self._contact_rows if row.you] @@ -408,6 +416,7 @@ class ContactListScreen(SelectScreen): row.value, ) ) + items.extend(self._tail) return items def _rebuild(self) -> None: diff --git a/meshterm/ui/contacts_screen.py b/meshterm/ui/contacts_screen.py index 6410698..2882435 100644 --- a/meshterm/ui/contacts_screen.py +++ b/meshterm/ui/contacts_screen.py @@ -9,15 +9,29 @@ location preview, the observed routes to it, and the ways in (trace, map, time m and backing out of that page returns to the list right where it stood. The one-shot CLI (``meshterm contacts --sort …``) still renders the static :func:`~meshterm.ui.widgets.contacts_table`; only the menu gets the live list. + +Below the contacts sits one maintenance action β€” **Purge stale contacts** β€” that sweeps out +the contacts a device has accumulated but no longer hears. It offers an age ladder (a week up +to a year, plus a *never heard* bucket), each rung showing a live count of how many contacts +it would remove, so the impact is visible before anything is chosen; the pick is then gated +behind a typed ``delete`` confirm. A purge deletes the contacts from the device's table and +forgets them from the cross-session store (see :mod:`~meshterm.core.contact_store`) so a +firmware-less bridge doesn't merge them back β€” but only the *contact* is dropped: each node's +reception history and overheard traffic in MeshTerm are untouched. Our own node, pinned above +the list, is never a purge candidate (it isn't in the device's contact table). """ from __future__ import annotations from typing import TYPE_CHECKING +from rich.text import Text + from .contactlist import ContactListScreen, ContactRow +from .menus import back_rows, menu_rows +from .tui import Choice, Separator from .tui.screen import CANCEL -from .widgets import ContactsSort, _contact_pkts +from .widgets import ContactsSort, _age_seconds, _contact_pkts if TYPE_CHECKING: from ..context import AppContext @@ -27,6 +41,57 @@ if TYPE_CHECKING: #: device answered) β€” Enter on it opens our own node's detail page. YOU = ("you",) +#: The contact-list tail sentinels (distinct from any :class:`~meshterm.core.models.Contact` +#: and from :data:`YOU`): the purge action row and the bare ``Back`` exit row. +_PURGE = ("purge",) +_BACK = ("back",) + +#: A day in seconds, for the purge age ladder. +_DAY = 86400 + +#: The age rungs the purge picker offers, ``(label, min_age_seconds)``. A contact qualifies +#: for a rung when its last-heard age is *at least* that long; a never-heard contact β€” one +#: with no advert time at all β€” is excluded here and swept only by the separate never-heard +#: bucket, so an age rung never quietly deletes a freshly-added contact that hasn't had time +#: to advert yet. +PURGE_RUNGS: tuple[tuple[str, int], ...] = ( + ("Older than 1 week", 7 * _DAY), + ("Older than 1 month", 30 * _DAY), + ("Older than 3 months", 90 * _DAY), + ("Older than 6 months", 180 * _DAY), + ("Older than 1 year", 365 * _DAY), +) + +#: The picker value for the never-heard bucket (contacts with no advert time at all). +_NEVER = "__never__" + + +def stale_past(contacts: "list[Contact]", min_age_seconds: float) -> "list[Contact]": + """Contacts last heard at least ``min_age_seconds`` ago. + + Never-heard contacts (no last-heard time) are *excluded* β€” they have their own bucket + (see :func:`never_heard`), so an age rung sweeps only contacts that were once heard and + have since gone quiet, never a contact that has simply not adverted yet. + """ + out: list["Contact"] = [] + for contact in contacts: + secs = _age_seconds(contact.last_seen) + if secs is not None and secs >= min_age_seconds: + out.append(contact) + return out + + +def never_heard(contacts: "list[Contact]") -> "list[Contact]": + """Contacts with no advert time at all β€” ones we have never heard broadcasting.""" + return [c for c in contacts if _age_seconds(c.last_seen) is None] + + +def _count_desc(n: int) -> str: + """The count shown against a purge rung: ``no contacts`` / ``1 contact`` / ``n contacts``.""" + if n == 0: + return "no contacts" + return f"{n} contact{'' if n == 1 else 's'}" + class ContactsScreen(ContactListScreen): """A full-screen, Ctrl+arrow-sortable list of this node and its known contacts. @@ -72,11 +137,25 @@ class ContactsScreen(ContactListScreen): count=_contact_pkts(c, counts), ) ) + # The maintenance action closes the list, past every contact whatever the sort: a + # blank spacer, the err-tinted purge row (a `…` β€” it opens further prompts), then the + # standard exit group. Offered only when there are contacts to purge. + tail: list = [] + if contacts: + tail = [ + Separator(" "), + Choice( + title=Text.assemble(("πŸ—‘ ", "err"), "Purge stale contacts…"), + value=_PURGE, + ), + *back_rows(_BACK), + ] super().__init__( f"Contacts Β· {len(contacts)} known", rows=rows, prefix_bytes=prefix_bytes, sort=sort, + tail=tail, ) @@ -92,8 +171,10 @@ async def open_contacts( """Open the interactive contacts list; Enter opens Node detail, Esc leaves. Runs the show/open/reshow loop: the sortable list, then whichever node's detail page - Enter commits, then the list again (same sort, the highlight kept on its row) β€” until - Esc backs out of the list itself. + Enter commits (or the purge flow the tail action opens), then the list again (same sort, + the highlight kept on its row) β€” until Esc, or the ``Back`` row, backs out of the list + itself. A purge that removes anything re-reads the device and rebuilds the list so the + swept contacts are gone from it. Args: ctx: Shared application context (must be in the interactive menu). @@ -119,7 +200,125 @@ async def open_contacts( screen = ContactsScreen(self_name, self_key, contacts, prefix_bytes, counts, sort) while True: chosen = await session.run_screen(screen) - if chosen is CANCEL or chosen is None: + if chosen is CANCEL or chosen is None or chosen == _BACK: return + if chosen == _PURGE: + # The purge picker and its confirm float over the list, so re-push it as the + # backdrop while they run (run_screen just popped it). A purge that removed + # anything invalidates the contacts cache, so re-read and rebuild the list. + session.push(screen) + try: + removed = await _purge_stale(ctx, self_key) + finally: + session.pop(screen) + if removed: + contacts = await ctx.devstate.contacts() + screen = ContactsScreen( + self_name, self_key, contacts, prefix_bytes, counts, sort + ) + continue # The own-node sentinel opens our own node's page; any other value is a Contact. await open_node_detail(ctx, None if chosen == YOU else chosen) + + +async def _purge_stale(ctx: "AppContext", self_key: str) -> int: + """Pick an age threshold, confirm, and remove every contact past it. Returns the count removed. + + Shows the age ladder (each rung carrying a live count of the contacts it would sweep, + plus a never-heard bucket), gates the pick behind a typed ``delete`` confirm, then deletes + each victim from the device's contact table and forgets it from the cross-session store so + a forgetful bridge doesn't merge it back. Only the *contact* is dropped β€” each node's + reception history in MeshTerm stays. Runs over the pushed contacts list as its backdrop. + + Args: + ctx: Shared application context (interactive menu). + self_key: The device's own public key (hex) β€” how the contact store scopes this + device's remembered contacts. + + Returns: + How many contacts were removed (``0`` if cancelled or nothing matched). + """ + from .surface import TuiUi + + assert isinstance(ctx.ui, TuiUi) # guaranteed by open_contacts + session = ctx.ui.session + + # Read fresh so the counts match the device right now (own node is never in this list, so + # a purge can't touch it). + contacts = await ctx.devstate.contacts() + + rungs = [(label, secs, stale_past(contacts, secs)) for label, secs in PURGE_RUNGS] + never = never_heard(contacts) + rows = [(label, _count_desc(len(victims)), secs) for label, secs, victims in rungs] + rows.append(("Never heard", _count_desc(len(never)), _NEVER)) + + from .tui import SelectScreen + + items = menu_rows(rows) + items.extend(back_rows(None)) + picked = await session.run_screen( + SelectScreen( + f"Purge stale contacts β€” {len(contacts)} known", + items, + prompt="Remove contacts you haven't heard from in the chosen span.", + footer_hint="↑↓ move Β· Enter pick Β· Esc back", + filterable=False, + wrap=False, + ) + ) + if picked is CANCEL or picked is None: + return 0 + + if picked == _NEVER: + victims = never + warning = ( + f"This deletes {_count_desc(len(victims))} you've never heard an advert from, " + "removing them from this device's contact list." + ) + else: + span = next(label for label, secs in PURGE_RUNGS if secs == picked).lower() + victims = stale_past(contacts, int(picked)) + warning = ( + f"This deletes {_count_desc(len(victims))} {span}, removing them from this " + "device's contact list. Their reception history in MeshTerm is kept." + ) + if not victims: + ctx.ui.note("[muted]no contacts that stale β€” nothing to purge[/muted]") + return 0 + + if not await ctx.ui.typed_confirm(warning, "delete", title="Purge stale contacts"): + return 0 + + device = await ctx.device() + dev_pub = (self_key or "").lower().removeprefix("0x") + store = ctx.contact_store + removed = 0 + failed = 0 + # A companion-local command per contact (no LoRa transmission), so a straight sequential + # sweep β€” not paced radio traffic β€” under a busy overlay for the slower links. + async with ctx.ui.busy_overlay( + f"Purging {_count_desc(len(victims))}…", title="Purge stale contacts" + ): + for contact in victims: + try: + await device.remove_contact(contact) + except Exception as exc: # noqa: BLE001 - one bad removal shouldn't abort the sweep + failed += 1 + ctx.log.debug("contacts: purge failed for %s: %s", contact.name, exc) + continue + if store is not None and dev_pub and contact.public_key: + store.forget(dev_pub, contact.public_key) + removed += 1 + # Drop the cached contact list so the rebuilt screen (and the dashboard) re-read the + # device without the swept contacts. + ctx.devstate.invalidate_contacts() + + if removed and not failed: + ctx.ui.note(f"[ok]βœ“[/ok] purged {_count_desc(removed)}") + elif removed: + ctx.ui.note( + f"[warn]purged {_count_desc(removed)}; {failed} could not be removed[/warn]" + ) + else: + ctx.ui.note("[err]no contacts could be removed[/err]") + return removed diff --git a/tests/test_device_config.py b/tests/test_device_config.py index c4b35ca..70b0edb 100644 --- a/tests/test_device_config.py +++ b/tests/test_device_config.py @@ -243,7 +243,7 @@ def test_contacts_screen_lists_contacts_in_the_shared_lanes() -> None: import re from meshterm.core.models import Contact, utcnow - from meshterm.ui.contacts_screen import YOU, ContactsScreen + from meshterm.ui.contacts_screen import _BACK, _PURGE, YOU, ContactsScreen from meshterm.ui.tui.screen import CANCEL contacts = [ @@ -264,8 +264,10 @@ def test_contacts_screen_lists_contacts_in_the_shared_lanes() -> None: assert "Alice" in body and "Bob" in body assert f"{7:>5}" in body # Alice's overheard packets, right-aligned in its lane assert "never" in body # Bob has no last_seen - # Each contact row carries the Contact itself, so Enter hands the whole record on. - assert all(isinstance(c.value, Contact) for c in choices[1:]) + # Each contact row carries the Contact itself, so Enter hands the whole record on; the + # tail closes the list with the purge action and the Back exit row. + assert [c.value for c in choices[-2:]] == [_PURGE, _BACK] + assert all(isinstance(c.value, Contact) for c in choices[1:-2]) # Plain arrows move the highlight without touching the sort. before = (screen._sort.column, screen._sort.ascending) @@ -284,6 +286,45 @@ def test_contacts_screen_lists_contacts_in_the_shared_lanes() -> None: assert resolved == [highlighted, CANCEL] +def test_purge_buckets_split_stale_from_never_heard() -> None: + """``stale_past`` counts heard-but-old contacts; never-heard falls only in its own bucket.""" + from datetime import timedelta + + from meshterm.core.models import Contact, utcnow + from meshterm.ui.contacts_screen import _DAY, never_heard, stale_past + + now = utcnow() + fresh = Contact(name="Fresh", public_key="aa" * 32, last_seen=now - timedelta(hours=1)) + old = Contact(name="Old", public_key="bb" * 32, last_seen=now - timedelta(days=45)) + ancient = Contact(name="Ancient", public_key="cc" * 32, last_seen=now - timedelta(days=400)) + unheard = Contact(name="Unheard", public_key="dd" * 32) # no last_seen + contacts = [fresh, old, ancient, unheard] + + # A week catches the two aged ones but not the fresh β€” and never the never-heard one. + week = {c.name for c in stale_past(contacts, 7 * _DAY)} + assert week == {"Old", "Ancient"} + # A year catches only the truly ancient. + assert {c.name for c in stale_past(contacts, 365 * _DAY)} == {"Ancient"} + # The never-heard bucket is exactly the contact with no advert time. + assert [c.name for c in never_heard(contacts)] == ["Unheard"] + + +def test_contacts_screen_tail_offers_purge_only_when_populated() -> None: + """A populated list closes with the purge action + Back; an empty one has no tail action.""" + from meshterm.core.models import Contact + from meshterm.ui.contacts_screen import _BACK, _PURGE, ContactsScreen + + populated = ContactsScreen( + "Us", "cc" * 32, [Contact(name="Alice", public_key="aa" * 32)], 1, {}, _contacts_sort() + ) + tail_values = [c.value for c in populated._choices()][-2:] + assert tail_values == [_PURGE, _BACK] + + empty = ContactsScreen("Us", "cc" * 32, [], 1, {}, _contacts_sort()) + values = [c.value for c in empty._choices()] + assert _PURGE not in values # nothing to purge β€” no action row + + def test_non_strict_enum_accepts_unlisted_value() -> None: """multi_acks/adv_loc_policy list common values but still accept other ints.""" spec = get_spec("multi_acks") diff --git a/tests/test_skeleton.py b/tests/test_skeleton.py index 198483a..f7be198 100644 --- a/tests/test_skeleton.py +++ b/tests/test_skeleton.py @@ -298,6 +298,21 @@ async def test_mock_device_honors_forced_path() -> None: assert [h.node for h in result.hops] == ["3d", "f2", "3d", None] +async def test_mock_device_remove_contact_drops_it_from_the_table() -> None: + """Removing a contact deletes it from the device's table (matched by public key).""" + device = MockDevice() + await device.connect() + before = await device.get_contacts() + alice = next(c for c in before if c.name == "Alice") + await device.remove_contact(alice) + after = await device.get_contacts() + assert "Alice" not in {c.name for c in after} + assert len(after) == len(before) - 1 + # Removing one already gone is a no-op, not an error. + await device.remove_contact(alice) + assert len(await device.get_contacts()) == len(after) + + async def test_mock_device_blank_path_traces() -> None: """A blank/auto path still produces a successful, non-empty trace.""" device = MockDevice()