Contacts: purge stale contacts by how long since last heard

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) <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 4.8 committed 2026-07-24 21:22:34 -04:00
1 parent 94e81a1b82
commit 3c38b366cf
5 files changed
+300 -9

No files matched your search

+27
View File
@@ -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
+11 -2
View File
@@ -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:
+203 -4
View File
@@ -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
+44 -3
View File
@@ -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")
+15
View File
@@ -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()