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:
1 parent
94e81a1b82
commit
3c38b366cf
5 files changed
+300
-9
No files matched your search
@@ -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
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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
|
||||
@@ -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")
|
||||
|
||||
@@ -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()
|
||||
|
||||
Reference in new issue
Block a user