Files
MeshTerm/meshterm/tools/clocks.py
T
Jean-Pierre MartineauandClaude Haiku 5.5 bdcdadc50c A Clock drift page shows which nodes have wrong clocks
A new Watch tool, "Clock drift" (meshterm clocks): a histogram of the
clock offsets in log steps on two sides, then the managed nodes, then
each other node out of sync, largest offset first; Enter opens the node
page. Channel senders with no key are listed by name. When most clocks
disagree with ours the same way, a note says our own clock may be wrong.
The CLI lists every sender with offset_s, samples, and flags. A new
clock_report_days preference sets the window. The demo world gets four
wrong clocks.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
2026-11-03 00:25:07 -05:00

228 lines
9.0 KiB
Python

# SPDX-License-Identifier: Apache-2.0
"""The ``clocks`` tool: how far the clock of each node is from ours.
A node with a wrong clock puts wrong times on its adverts and its messages. MeshTerm shows
the arrival time in place of a wrong sender time (refer to
:meth:`~meshterm.core.models.ChatMessage.corrected`), but the owner of the node is the only
one who can set the clock. This tool says which nodes to tell, and by how much they are off.
The menu opens the Clock drift page (refer to :mod:`meshterm.ui.clocks_screen`): a
histogram of the offsets, the managed nodes, and the nodes out of sync. Enter opens the
node page. The CLI prints one row for each sender with a clock sample in the window, the
largest offset first.
"""
from __future__ import annotations
from datetime import timedelta
from typing import TYPE_CHECKING, Any
import typer
from ..context import AppContext
from ..core import exitcodes
from ..core.models import NODE_TYPE_LABELS, Contact, utcnow
from .base import Tool, ToolResult, register
if TYPE_CHECKING: # pragma: no cover - typing only
from ..ui.clocks_screen import ClockRow
from ..ui.report import Listing
@register
class ClocksTool(Tool):
"""Show the clock offset of each node heard, and the nodes whose clocks are wrong."""
name = "clocks"
title = "Clock drift"
icon = "🕒"
help = "Nodes whose clocks are wrong — offsets, histogram"
category = "Watch"
order = 35 # after the Watchtower, before the Time machine: one more report on the mesh
async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult:
"""Measure the clock offsets of the window, and show them.
Args:
ctx: The shared application context.
params: Not used.
Returns:
A :class:`ToolResult` with the counts, and the listing for the CLI.
"""
from ..ui.surface import TuiUi
tolerance = ctx.preferences.clock_tolerance_s
rows = await clock_rows(ctx)
off = sum(1 for r in rows if r.offset.out_of_sync(tolerance))
summary = {"senders": len(rows), "out_of_sync": off}
if isinstance(ctx.ui, TuiUi):
await _open_page(ctx, rows, tolerance)
return ToolResult(summary=summary)
# The hash has the path hash width of the device, as in ``contacts``: it is the
# token that ``--path`` takes. A key prefix is not a hash.
try:
mode = await ctx.devstate.path_hash_mode()
except Exception: # noqa: BLE001 - an optional read. If it is absent, no hash.
mode = None
prefix_bytes = (mode + 1) if isinstance(mode, int) and 0 <= mode <= 3 else 0
return ToolResult(
summary=summary,
report=(_listing(rows, tolerance, prefix_bytes),),
exit_code=exitcodes.OK if rows else exitcodes.NO_RESULT,
)
def register_cli(self, app: typer.Typer) -> None:
"""Register the ``clocks`` subcommand.
Args:
app: The Typer application.
"""
from ..cli import run_tool_command
@app.command(name=self.name, help=self.help)
def _clocks() -> None:
run_tool_command(self, {})
async def clock_rows(ctx: AppContext) -> list[ClockRow]:
"""One row for each sender with a clock sample in the window of ``clock_report_days``.
A keyed row gets the contact of the device when there is one, and else a contact made
from the stored history, so that Enter can open its node page. Our own node is not a
row: MeshTerm sets the clock of the companion itself when it connects.
Args:
ctx: The shared application context.
Returns:
The rows, in no specific order.
"""
from ..services.clock_offsets import offsets, window_samples
from ..services.trace_runner import make_name_key_resolver
from ..ui.clocks_screen import ClockRow
since = utcnow() - timedelta(days=ctx.preferences.clock_report_days)
try:
contacts = await ctx.devstate.contacts()
except Exception: # noqa: BLE001 - the stored history still names the nodes
contacts = []
try:
info = await ctx.devstate.self_info()
except Exception: # noqa: BLE001 - without our key, our own adverts are a row
info = {}
self_id = str(info.get("public_key") or "").lower().removeprefix("0x")[:12]
stored_names, named_at = ctx.repo.node_names_with_times()
key_of = make_name_key_resolver(contacts, stored_names, heard=named_at)
found = offsets(window_samples(ctx.repo, since=since, key_of=key_of))
by_id = {
(c.public_key or c.key_prefix or "").lower().removeprefix("0x")[:12]: c for c in contacts
}
heard = {n.node: n for n in ctx.repo.heard_nodes() if n.node}
admin = getattr(ctx, "admin_store", None)
rows: list[ClockRow] = []
for offset in found:
if not offset.keyed:
rows.append(ClockRow(offset, None, None, None, False, None))
continue
if self_id and offset.who == self_id:
continue
contact = by_id.get(offset.who)
hn = heard.get(offset.who)
name = (contact.name if contact else None) or stored_names.get(offset.who)
name = name or (hn.name if hn else None)
if contact is None:
contact = Contact(
name=name or offset.who,
public_key=(hn.public_key or "") if hn else "",
key_prefix=offset.who,
last_seen=hn.last_seen if hn else None,
node_type=hn.node_type if hn else None,
lat=hn.lat if hn else None,
lon=hn.lon if hn else None,
)
key = contact.public_key or contact.key_prefix
managed = admin is not None and admin.get(contact) is not None
rows.append(ClockRow(offset, name, key, contact.node_type, managed, contact))
return rows
async def _open_page(ctx: AppContext, rows: list[ClockRow], tolerance: float) -> None:
"""Run the Clock drift page. Enter opens the node page, and Esc comes back to the row."""
from ..ui.clocks_screen import clock_drift_screen
from ..ui.node_detail_screen import open_node_detail
from ..ui.surface import TuiUi
from ..ui.tui.screen import CANCEL
assert isinstance(ctx.ui, TuiUi)
session = ctx.ui.session
screen = clock_drift_screen(rows, tolerance_s=tolerance)
async with session.stay(screen) as visit:
while True:
chosen = await visit.result()
if chosen is CANCEL or chosen is None:
return
# The page opens to look. The verbs that manage a contact belong to the
# Contacts list, and this page is not that list.
await open_node_detail(ctx, chosen, manage=False)
def _listing(rows: list[ClockRow], tolerance: float, prefix_bytes: int = 0) -> Listing:
"""The senders, the largest offset first, stated one time for the two faces.
``OFFSET`` is the offset in words (``3h 12m behind``, or ``in sync`` within the
tolerance). The document gives ``offset_s``, signed, a positive value for a clock
ahead of ours. A sender with no key has only its name, and ``keyed`` is false.
Args:
rows: The senders.
tolerance: The ``clock_tolerance_s`` preference.
prefix_bytes: The path hash width of the device. ``HASH`` is that many bytes of
the key, so that ``--path`` takes it. ``0`` gives no hash.
"""
from ..ui import fields
from ..ui.report import Column, Lane, Listing
from ..ui.widgets import format_offset
def words(seconds: float) -> str:
return "in sync" if abs(seconds) <= tolerance else format_offset(seconds)
table = []
for row in sorted(rows, key=lambda r: -abs(r.offset.offset_s)):
key = (row.contact.public_key or "").lower() if row.contact else ""
known = key or (row.offset.who if row.offset.keyed else "")
table.append(
{
"node": fields.NodeRef(
name=row.name or (None if row.offset.keyed else row.offset.who),
key=key or None,
hash=known[: prefix_bytes * 2] or None,
type=NODE_TYPE_LABELS.get(row.node_type),
),
"offset_s": round(row.offset.offset_s),
"samples": row.offset.samples,
"last_sample_at": row.offset.last_at,
"out_of_sync": row.offset.out_of_sync(tolerance),
"managed": row.managed,
"keyed": row.offset.keyed,
}
)
return Listing(
key="clocks",
columns=(
fields.node("node", lanes=(("name", "NAME"), ("type", "TYPE"), ("hash", "HASH"))),
Column(
key="offset_s",
lanes=(Lane(header="OFFSET", render=words, align="right"),),
json=lambda v: v,
),
fields.integer("samples", "SAMPLES"),
fields.when("last_sample_at", "LAST"),
fields.hidden("out_of_sync"),
fields.flag("managed", "MANAGED"),
fields.hidden("keyed"),
),
rows=table,
)