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>
228 lines
9.0 KiB
Python
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,
|
|
)
|