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>
This commit is contained in:
1 parent
adb79d051a
commit
bdcdadc50c
11 files changed
+795
-5
No files matched your search
@@ -278,7 +278,8 @@ error message that MeshTerm gives.
|
||||
|
||||
The menu asks one question: *what would you like to do?* It gives the answer in two halves.
|
||||
Three sections name an activity. **Message** has chat, channels, the courier outbox, and
|
||||
contacts. **Watch** has the dashboard, the live feed, the watchtower, and the time machine.
|
||||
contacts. **Watch** has the dashboard, the live feed, the watchtower, the clock drift
|
||||
report, and the time machine.
|
||||
**Explore** has the map, the mesh walk, tracing, and the trophy case. The other three
|
||||
sections name the owner. **This node** is the radio in your hand. **Other nodes** is the
|
||||
someone else's radio, which you reach over the mesh. **This app** is MeshTerm itself, with
|
||||
|
||||
@@ -1052,6 +1052,47 @@ correct.
|
||||
|
||||
The command returns `5` and `[]` when no records match.
|
||||
|
||||
#### `meshterm clocks`
|
||||
|
||||
How far the clock of each node is from the clock of this computer. The command reads the
|
||||
database. It needs no device and never transmits. A node with a wrong clock puts wrong
|
||||
times on its adverts and messages, and only its owner can set the clock. This listing
|
||||
tells you which owners to tell.
|
||||
|
||||
Each advert, direct message, and channel message that MeshTerm heard is a clock sample:
|
||||
the time that the sender wrote, minus the time when MeshTerm heard it. The offset of a node
|
||||
is the median of its three newest samples. The listing has each sender with a sample in
|
||||
the last `clock_report_days` (a preference, 7 by default), the largest offset first.
|
||||
|
||||
```console
|
||||
$ meshterm --demo clocks
|
||||
NAME TYPE HASH OFFSET SAMPLES LAST MANAGED
|
||||
Île-Bizard repeater 3cc49c 2y 5w behind 16 3h no
|
||||
Wio Tracker companion a09028 3d 7h behind 32 1d no
|
||||
Steve K. companion 220c44 5h behind 38 24m no
|
||||
Gabriel companion 7fc6ea 1h 24m ahead 40 21m no
|
||||
Chloé L. companion c9d961 in sync 48 9h no
|
||||
```
|
||||
|
||||
`OFFSET` is `in sync` when the offset is within the `clock_tolerance_s` preference (300 s
|
||||
by default). `LAST` is the age of the newest sample. `MANAGED` is `yes` when MeshTerm
|
||||
stores the admin password of the node. A channel sender whose name matches no single key
|
||||
has only its name, with no `TYPE` and no `HASH`.
|
||||
|
||||
**`--json`** is an array of rows.
|
||||
|
||||
| Field | Type | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `node` | object | The `node` shape. A sender with no key has only `name`. |
|
||||
| `offset_s` | integer | The offset in seconds. A positive value is a clock ahead of this computer. |
|
||||
| `samples` | integer | The number of samples in the window. |
|
||||
| `last_sample_at` | timestamp | When MeshTerm heard the newest sample. |
|
||||
| `out_of_sync` | boolean | **JSON only.** `true` when the offset is past `clock_tolerance_s`. It is the `in sync` of the plain face, inverted. |
|
||||
| `managed` | boolean | `true` when MeshTerm stores the admin password of the node. |
|
||||
| `keyed` | boolean | **JSON only.** `false` for a channel sender that has only a name. |
|
||||
|
||||
The command returns `5` and `[]` when the window has no sample.
|
||||
|
||||
---
|
||||
|
||||
### Messaging
|
||||
|
||||
@@ -28,6 +28,7 @@ This page lists each interactive screen with its scripted equivalent, where one
|
||||
| **📊 Dashboard** | The live overview of the mesh. It has a two-hour chart of the activity of all packets with a pulse line, the traffic counts of the session for each packet class, and window RF health next to the live numbers of the radio. The screen updates each second. | none |
|
||||
| **📰 Live feed** | Each packet as it arrives, newest first. A row shows the time, the type of the packet (its parsed payload class), and what the packet is about. For an advert, that is the node. For a channel text, it is the channel. For a direct message or a request, it is sender → recipient. For a trace, it is the tag. The row also shows the reception quality and, for a scoped flood, the region of the flood. Press Enter to open a row in the packet viewer, with its route graph. | none |
|
||||
| **🚨 Watchtower** | A passive watcher of the nodes that you star. It gives a silence alarm when a watched node goes quiet. It warns you when the SNR of a node gets worse, and it tells you when the node returns. It also tells you when a node is heard for the first time. It runs in the background during the whole session. Alerts that you did not acknowledge show as a badge in the header. | none |
|
||||
| **🕒 Clock drift** | How far the clock of each node is from yours. A node with a wrong clock puts wrong times on what it sends, and only its owner can set it. The page has a histogram of the offsets, from the clocks behind yours, through the clocks in sync, to the clocks ahead. Then it lists your managed nodes (the nodes whose admin password MeshTerm stores), and each other node whose clock is out of sync, the largest offset first. Press Enter to open the node page. In a chat, a message from a wrong clock shows the time when it arrived, with a `?` mark. | `meshterm clocks` |
|
||||
| **⏳ Time machine** | Everything that the recorder ever heard, as braille charts: reception volume, the median-SNR band, the rhythm of the hours of the day, packets and nodes for each day, and first-ever arrivals. You can switch the time window between 24h, 7d, 30d, and all time. On the PicoCalc, the windows stop at 30d. You can look at one node or at the whole mesh. | none |
|
||||
| **🎧 Monitor** | The app always records passively. On the command line, this command captures a window of a fixed length in the foreground. It shows each overheard packet as it arrives, and it gives a summary at the end. It transmits nothing. It only listens. | `meshterm monitor --seconds 60` |
|
||||
|
||||
|
||||
@@ -535,6 +535,19 @@ PREFERENCES: tuple[PrefSpec, ...] = (
|
||||
maximum=86400,
|
||||
unit="s",
|
||||
),
|
||||
PrefSpec(
|
||||
key="clock_report_days",
|
||||
label="Clock report",
|
||||
help="How many days of packets the Clock drift page reads",
|
||||
group="Display",
|
||||
value_type="int",
|
||||
# A week: long enough to hear each repeater advert a few times, and short enough
|
||||
# that a clock that its owner set last month no longer counts against the node.
|
||||
default=7,
|
||||
minimum=1,
|
||||
maximum=365,
|
||||
unit="days",
|
||||
),
|
||||
PrefSpec(
|
||||
key="section_spacing_min_rows",
|
||||
label="Section spacing",
|
||||
|
||||
@@ -48,6 +48,7 @@ from .world import (
|
||||
Copy,
|
||||
Node,
|
||||
best_route,
|
||||
clock_offset_s,
|
||||
flood,
|
||||
link_snr,
|
||||
loss_chance,
|
||||
@@ -556,8 +557,23 @@ def traffic(start_s: float, end_s: float, seed: str) -> list[Heard]:
|
||||
|
||||
|
||||
def stamp(heard: list[Heard], now: datetime) -> list[Heard]:
|
||||
"""Give each observation in ``heard`` its time, from ``now`` and its offset."""
|
||||
"""Give each observation in ``heard`` its time, from ``now`` and its offset.
|
||||
|
||||
An advert packet also gets its own time, as its node wrote it: the time of the
|
||||
reception, moved by the clock offset of that node (refer to
|
||||
:data:`~meshterm.demo.world.CLOCK_OFFSET_S`).
|
||||
"""
|
||||
for item in heard:
|
||||
if item.observation is not None:
|
||||
item.observation.observed_at = now + timedelta(seconds=item.offset_s)
|
||||
obs = item.observation
|
||||
if obs is None:
|
||||
continue
|
||||
obs.observed_at = now + timedelta(seconds=item.offset_s)
|
||||
raw = obs.raw
|
||||
if (
|
||||
obs.kind == "packet"
|
||||
and isinstance(raw, dict)
|
||||
and raw.get("payload_typename") == "ADVERT"
|
||||
):
|
||||
sent = obs.observed_at + timedelta(seconds=clock_offset_s(obs.name or ""))
|
||||
raw["adv_timestamp"] = int(sent.timestamp())
|
||||
return heard
|
||||
@@ -191,6 +191,25 @@ NODES: tuple[Node, ...] = (
|
||||
#: Each node of the world by name, our node included.
|
||||
BY_NAME: dict[str, Node] = {node.name: node for node in (SELF, *NODES)}
|
||||
|
||||
#: The nodes whose clocks are wrong, and by how much (seconds, a positive value is ahead).
|
||||
#: Each other clock is correct. These are the usual faults of a real mesh: a repeater that
|
||||
#: lost its time at a reboot and starts from its build date, a tracker that was never set,
|
||||
#: and two phones set to the wrong time zone. The adverts carry these times, so the Clock
|
||||
#: drift page and the node pages have something to show (refer to
|
||||
#: :mod:`~meshterm.services.clock_offsets`).
|
||||
CLOCK_OFFSET_S: dict[str, float] = {
|
||||
"Île-Bizard": -(2 * 365 + 40) * 86400.0,
|
||||
"Wio Tracker": -(3 * 86400.0 + 7 * 3600.0),
|
||||
"Steve K.": -5 * 3600.0,
|
||||
"Gabriel": 3600.0 + 25 * 60.0,
|
||||
}
|
||||
|
||||
|
||||
def clock_offset_s(name: str) -> float:
|
||||
"""How far the clock of the node with this name is from the real time, in seconds."""
|
||||
return CLOCK_OFFSET_S.get(name, 0.0)
|
||||
|
||||
|
||||
#: The repeaters, in the order of :data:`NODES`.
|
||||
REPEATERS: tuple[Node, ...] = tuple(node for node in NODES if node.is_repeater)
|
||||
|
||||
|
||||
@@ -0,0 +1,227 @@
|
||||
# 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,
|
||||
)
|
||||
@@ -0,0 +1,283 @@
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
"""The Clock drift page: how far the clock of each node is from ours.
|
||||
|
||||
The page reads the clock samples of the last ``clock_report_days`` (refer to
|
||||
:mod:`~meshterm.services.clock_offsets`) and shows them in three parts:
|
||||
|
||||
* **A histogram** of the offsets, in log steps on two sides: the clocks behind ours at the
|
||||
top, the clocks in sync in the centre, and the clocks ahead at the bottom (JP,
|
||||
2026-11-02). A clock can be wrong by seconds or by years, so one linear axis cannot
|
||||
show the two. The centre row is as wide as the ``clock_tolerance_s`` preference. Each bar
|
||||
is a :func:`~meshterm.ui.braillechart.meter`, the only bar of the app.
|
||||
* **The nodes**, in two sections. *Managed nodes* (the nodes whose admin password
|
||||
MeshTerm stores) are first, each one also when its clock is correct, because these are
|
||||
the clocks that the user can set. Then *Out of sync*: each other node past the
|
||||
tolerance, the largest offset first. Enter opens the node page.
|
||||
* **The senders with no key**: the channel senders whose name resolves to no single key.
|
||||
Their samples count in the histogram, and their names are page text under their own
|
||||
heading, in the grey of an unknown node. There is no node page to open for a name.
|
||||
|
||||
When most clocks are off in the same direction, the fault is probably ours. A note at the
|
||||
top then says that the clock of this computer can be wrong.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import statistics
|
||||
from collections.abc import Sequence
|
||||
from dataclasses import dataclass
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
from rich.text import Text
|
||||
|
||||
from ..services.clock_offsets import ClockOffset
|
||||
from .braillechart import meter
|
||||
from .menus import fit_cells, section_heading
|
||||
from .theme import name_style
|
||||
from .tui import Choice, Separator
|
||||
from .tui.select import SelectScreen
|
||||
from .widgets import DEFAULT_GLYPH, NODE_GLYPHS, age_seconds, format_age, format_offset
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from ..core.models import Contact
|
||||
|
||||
#: The edges of the histogram steps past the tolerance, in seconds: an hour, a day, a year.
|
||||
#: An edge at or under the tolerance is dropped, so a large tolerance gives fewer steps.
|
||||
_EDGES_S = (3600, 86400, 365 * 86400)
|
||||
|
||||
#: The cells of the label lane of the histogram (``1d–1y behind``).
|
||||
_BUCKET_LABEL_W = 14
|
||||
|
||||
#: The cells of the offset lane of a row (``11h 59m behind``) and of its age lane (``52w``).
|
||||
_OFFSET_W = 15
|
||||
_AGE_W = 4
|
||||
|
||||
#: The widest that a name lane gets. The filter measures a row at an unbounded width.
|
||||
_NAME_MAX_W = 24
|
||||
|
||||
#: The smallest number of keyed nodes from which the page judges our own clock.
|
||||
_OWN_CLOCK_MIN_NODES = 5
|
||||
|
||||
#: The share of the keyed nodes that must be off in one direction to blame our clock.
|
||||
_OWN_CLOCK_SHARE = 0.6
|
||||
|
||||
#: The footer hint. Enter opens the node page of the highlighted row.
|
||||
_HINT = "↑↓ move · Enter open · type to filter · Esc back"
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class ClockRow:
|
||||
"""One sender on the Clock drift page.
|
||||
|
||||
Attributes:
|
||||
offset: Its clock offset (refer to :class:`~meshterm.services.clock_offsets.ClockOffset`).
|
||||
name: The name to show, or ``None`` when nothing names the node.
|
||||
key: The key (or key prefix) that gives the hue of the name, or ``None``.
|
||||
node_type: The advert type of the node, if known.
|
||||
managed: Whether MeshTerm stores the admin password of the node.
|
||||
contact: What Enter opens, or ``None`` for a sender with no key.
|
||||
"""
|
||||
|
||||
offset: ClockOffset
|
||||
name: str | None
|
||||
key: str | None
|
||||
node_type: int | None
|
||||
managed: bool
|
||||
contact: Contact | None
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class Bucket:
|
||||
"""One step of the histogram.
|
||||
|
||||
Attributes:
|
||||
label: The words of the step (``1h–1d behind``, ``in sync ±5m``).
|
||||
low: The smallest offset in the step, in seconds (``None`` for no limit).
|
||||
high: The largest offset in the step, in seconds (``None`` for no limit).
|
||||
in_sync: Whether this is the centre step.
|
||||
"""
|
||||
|
||||
label: str
|
||||
low: float | None
|
||||
high: float | None
|
||||
in_sync: bool = False
|
||||
|
||||
def holds(self, offset_s: float) -> bool:
|
||||
"""Whether ``offset_s`` falls in this step. A step includes its edge farthest from zero."""
|
||||
if self.in_sync:
|
||||
assert self.low is not None and self.high is not None
|
||||
return self.low <= offset_s <= self.high
|
||||
if offset_s < 0:
|
||||
return (self.low is None or offset_s >= self.low) and (
|
||||
self.high is None or offset_s < self.high
|
||||
)
|
||||
return (self.low is None or offset_s > self.low) and (
|
||||
self.high is None or offset_s <= self.high
|
||||
)
|
||||
|
||||
|
||||
def _span(seconds: float) -> str:
|
||||
"""A step edge in the compact age form, with years: ``5m``, ``1h``, ``1d``, ``1y``."""
|
||||
return "1y" if seconds >= 365 * 86400 else format_age(seconds)
|
||||
|
||||
|
||||
def buckets(tolerance_s: float) -> list[Bucket]:
|
||||
"""The steps of the histogram, the clocks most behind first.
|
||||
|
||||
Args:
|
||||
tolerance_s: The ``clock_tolerance_s`` preference: the half width of the centre.
|
||||
|
||||
Returns:
|
||||
The steps, from the farthest behind, through "in sync", to the farthest ahead.
|
||||
"""
|
||||
edges = [float(tolerance_s)] + [float(e) for e in _EDGES_S if e > tolerance_s]
|
||||
ahead: list[Bucket] = []
|
||||
for low, high in zip(edges, [*edges[1:], None], strict=True):
|
||||
# A plain hyphen, not an en dash: the console font of the PicoCalc has no en dash.
|
||||
words = f"{_span(low)}-{_span(high)}" if high is not None else f"> {_span(low)}"
|
||||
ahead.append(Bucket(f"{words} ahead", low, high))
|
||||
behind = [
|
||||
Bucket(
|
||||
b.label.replace("ahead", "behind"),
|
||||
-b.high if b.high is not None else None,
|
||||
-b.low if b.low is not None else None,
|
||||
)
|
||||
for b in reversed(ahead)
|
||||
]
|
||||
# ``≤`` and not ``±``: the console font of the PicoCalc has no ``±``, and its fold to
|
||||
# ``?`` would read as the mark of a corrected time.
|
||||
centre = Bucket(f"in sync ≤{_span(tolerance_s)}", -tolerance_s, tolerance_s, in_sync=True)
|
||||
return [*behind, centre, *ahead]
|
||||
|
||||
|
||||
def histogram(rows: Sequence[ClockRow], tolerance_s: float) -> list[tuple[Bucket, int]]:
|
||||
"""Count the senders in each step of :func:`buckets`."""
|
||||
steps = buckets(tolerance_s)
|
||||
counts = [0] * len(steps)
|
||||
for row in rows:
|
||||
for i, step in enumerate(steps):
|
||||
if step.holds(row.offset.offset_s):
|
||||
counts[i] += 1
|
||||
break
|
||||
return list(zip(steps, counts, strict=True))
|
||||
|
||||
|
||||
def own_clock_note(rows: Sequence[ClockRow], tolerance_s: float) -> str | None:
|
||||
"""A note when most clocks are off in one direction, so that the fault is probably ours.
|
||||
|
||||
Args:
|
||||
rows: All the senders on the page.
|
||||
tolerance_s: The ``clock_tolerance_s`` preference.
|
||||
|
||||
Returns:
|
||||
The note, or ``None`` when the clocks do not agree against ours.
|
||||
"""
|
||||
keyed = [r.offset.offset_s for r in rows if r.offset.keyed]
|
||||
if len(keyed) < _OWN_CLOCK_MIN_NODES:
|
||||
return None
|
||||
median = statistics.median(keyed)
|
||||
if abs(median) <= tolerance_s:
|
||||
return None
|
||||
same_way = sum(1 for o in keyed if abs(o) > tolerance_s and (o > 0) == (median > 0))
|
||||
if same_way < _OWN_CLOCK_SHARE * len(keyed):
|
||||
return None
|
||||
direction = "ahead of" if median > 0 else "behind"
|
||||
size = format_offset(median).rsplit(" ", 1)[0]
|
||||
return f"⚠ most clocks are {size} {direction} this computer — its own clock may be wrong"
|
||||
|
||||
|
||||
def _bar_row(step: Bucket, count: int, peak: int, width: int) -> Text:
|
||||
"""One line of the histogram: the label, the count, and the bar.
|
||||
|
||||
The count is between the label and the bar, in a lane as wide as the largest count.
|
||||
Thus each count is next to its label, also when its bar is short or absent.
|
||||
"""
|
||||
count_w = len(str(peak))
|
||||
bar_w = max(1, width - _BUCKET_LABEL_W - 1 - count_w - 1)
|
||||
text = Text(no_wrap=True, overflow="ellipsis")
|
||||
text.append(fit_cells(step.label, _BUCKET_LABEL_W), style="muted")
|
||||
text.append(" ")
|
||||
text.append(f"{count:>{count_w}}", style="muted" if count else "faint")
|
||||
text.append(" ")
|
||||
style = "ok" if step.in_sync else "warn"
|
||||
text.append_text(meter(count / peak if count else None, bar_w, style=style))
|
||||
return text
|
||||
|
||||
|
||||
def _row_text(row: ClockRow, tolerance_s: float, width: int) -> Text:
|
||||
"""One node: its type mark, its name in its hue, its offset, and the age of its sample."""
|
||||
glyph, glyph_style = NODE_GLYPHS.get(row.node_type, DEFAULT_GLYPH)
|
||||
name_w = max(4, min(_NAME_MAX_W, width - 2 - 2 - _OFFSET_W - 2 - _AGE_W))
|
||||
text = Text(no_wrap=True, overflow="ellipsis")
|
||||
text.append(f"{glyph} ", style=glyph_style)
|
||||
# A node that nothing names shows its id in the grey of an unknown node: a bare hash
|
||||
# that stands in for a name never takes a hue.
|
||||
hue = name_style(row.name, row.key) if row.name else "node.unknown"
|
||||
text.append(fit_cells(row.name or row.offset.who, name_w), style=hue)
|
||||
text.append(" ")
|
||||
if row.offset.out_of_sync(tolerance_s):
|
||||
text.append(fit_cells(format_offset(row.offset.offset_s), _OFFSET_W, align="right"), "warn")
|
||||
else:
|
||||
text.append(fit_cells("in sync", _OFFSET_W, align="right"))
|
||||
text.append(" ")
|
||||
age = format_age(age_seconds(row.offset.last_at))
|
||||
text.append(fit_cells(age, _AGE_W, align="right"), style="muted")
|
||||
return text
|
||||
|
||||
|
||||
def _name_line(row: ClockRow, tolerance_s: float, width: int) -> Text:
|
||||
"""One sender with no key: page text under the row column, in the unknown grey."""
|
||||
name_w = max(4, min(_NAME_MAX_W, width - 4 - 2 - _OFFSET_W - 2 - _AGE_W))
|
||||
text = Text(no_wrap=True, overflow="ellipsis")
|
||||
text.append(" ") # the pointer and the type mark of a row: no node, no mark
|
||||
text.append(fit_cells(row.offset.who, name_w), style="node.unknown")
|
||||
text.append(" ")
|
||||
text.append(fit_cells(format_offset(row.offset.offset_s), _OFFSET_W, align="right"), "warn")
|
||||
text.append(" ")
|
||||
age = format_age(age_seconds(row.offset.last_at))
|
||||
text.append(fit_cells(age, _AGE_W, align="right"), style="muted")
|
||||
return text
|
||||
|
||||
|
||||
def _by_size(rows: Sequence[ClockRow]) -> list[ClockRow]:
|
||||
"""The largest offset first."""
|
||||
return sorted(rows, key=lambda r: -abs(r.offset.offset_s))
|
||||
|
||||
|
||||
def clock_drift_screen(rows: Sequence[ClockRow], *, tolerance_s: float) -> SelectScreen:
|
||||
"""Build the Clock drift page from its rows.
|
||||
|
||||
Args:
|
||||
rows: Each sender with a clock sample in the window, keyed or not.
|
||||
tolerance_s: The ``clock_tolerance_s`` preference.
|
||||
|
||||
Returns:
|
||||
The screen. It resolves with the :class:`~meshterm.core.models.Contact` of the
|
||||
chosen row.
|
||||
"""
|
||||
off = [r for r in rows if r.offset.out_of_sync(tolerance_s)]
|
||||
title = f"Clock drift · {len(rows)} nodes · {len(off)} out of sync"
|
||||
items: list = []
|
||||
note = own_clock_note(rows, tolerance_s)
|
||||
if note is not None:
|
||||
items.append(Separator(note, style="warn"))
|
||||
counted = histogram(rows, tolerance_s)
|
||||
peak = max((count for _step, count in counted), default=0) or 1
|
||||
for step, count in counted:
|
||||
items.append(Separator(lambda w, s=step, c=count: _bar_row(s, c, peak, w)))
|
||||
|
||||
managed = _by_size([r for r in rows if r.managed and r.contact is not None])
|
||||
others = _by_size([r for r in off if not r.managed and r.contact is not None])
|
||||
nameless = _by_size([r for r in off if not r.offset.keyed])
|
||||
if managed:
|
||||
items.append(section_heading("Managed nodes"))
|
||||
items += [Choice(lambda w, r=r: _row_text(r, tolerance_s, w), r.contact) for r in managed]
|
||||
items.append(section_heading("Out of sync"))
|
||||
if others:
|
||||
items += [Choice(lambda w, r=r: _row_text(r, tolerance_s, w), r.contact) for r in others]
|
||||
else:
|
||||
items.append(Separator("no other clock is out of sync", style="muted"))
|
||||
if nameless:
|
||||
items.append(section_heading("Senders with no key"))
|
||||
items += [Separator(lambda w, r=r: _name_line(r, tolerance_s, w)) for r in nameless]
|
||||
return SelectScreen(title, items, footer_hint=_HINT)
|
||||
@@ -0,0 +1,156 @@
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
"""The Clock drift page and the ``clocks`` command: the histogram, the sections, the rows."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import logging
|
||||
from datetime import timedelta
|
||||
from pathlib import Path
|
||||
|
||||
from meshterm.core.admin_store import AdminStore
|
||||
from meshterm.core.models import NODE_TYPE_REPEATER, ChatMessage, Contact, Message, utcnow
|
||||
from meshterm.core.preferences import Preferences
|
||||
from meshterm.persistence.repository import Repository
|
||||
from meshterm.services.clock_offsets import ClockOffset
|
||||
from meshterm.tools.clocks import _listing, clock_rows
|
||||
from meshterm.ui.clocks_screen import (
|
||||
ClockRow,
|
||||
buckets,
|
||||
clock_drift_screen,
|
||||
histogram,
|
||||
own_clock_note,
|
||||
)
|
||||
from tests.conftest import plain
|
||||
|
||||
TOLERANCE = 300
|
||||
|
||||
|
||||
def _row(name: str, offset_s: float, *, managed: bool = False, keyed: bool = True) -> ClockRow:
|
||||
key = (name.encode().hex() * 32)[:64]
|
||||
who = key[:12] if keyed else name
|
||||
offset = ClockOffset(who, keyed, offset_s, 3, utcnow() - timedelta(minutes=5))
|
||||
contact = Contact(name=name, public_key=key) if keyed else None
|
||||
return ClockRow(offset, name, key if keyed else None, None, managed, contact)
|
||||
|
||||
|
||||
def test_the_steps_run_from_behind_through_in_sync_to_ahead() -> None:
|
||||
"""The centre step is the tolerance. Each step past it is an hour, a day, a year."""
|
||||
labels = [b.label for b in buckets(TOLERANCE)]
|
||||
assert labels == [
|
||||
"> 1y behind",
|
||||
"1d-1y behind",
|
||||
"1h-1d behind",
|
||||
"5m-1h behind",
|
||||
"in sync ≤5m",
|
||||
"5m-1h ahead",
|
||||
"1h-1d ahead",
|
||||
"1d-1y ahead",
|
||||
"> 1y ahead",
|
||||
]
|
||||
# A tolerance of two hours leaves no step between it and the hour.
|
||||
wide = [b.label for b in buckets(7200)]
|
||||
assert wide[2:5] == ["2h-1d behind", "in sync ≤2h", "2h-1d ahead"]
|
||||
|
||||
|
||||
def test_each_offset_falls_in_exactly_one_step() -> None:
|
||||
"""The edges belong to one step each, so no sender counts twice or not at all."""
|
||||
rows = [_row(f"n{i}", s) for i, s in enumerate((-300, 300, -3600, 3600, 0, -4e8, 4e8))]
|
||||
counted = dict((b.label, n) for b, n in histogram(rows, TOLERANCE))
|
||||
assert sum(counted.values()) == len(rows)
|
||||
assert counted["in sync ≤5m"] == 3 # -300, 0, and 300
|
||||
assert counted["5m-1h behind"] == 1 and counted["5m-1h ahead"] == 1
|
||||
assert counted["> 1y behind"] == 1 and counted["> 1y ahead"] == 1
|
||||
|
||||
|
||||
def test_most_clocks_ahead_blame_our_own_clock() -> None:
|
||||
"""When most keyed clocks agree against ours, the fault is probably ours."""
|
||||
agree = [_row(f"n{i}", 2 * 3600 + i) for i in range(6)]
|
||||
note = own_clock_note(agree, TOLERANCE)
|
||||
assert note is not None and "2h ahead of this computer" in note
|
||||
mixed = [_row(f"n{i}", (-1) ** i * 7200) for i in range(6)]
|
||||
assert own_clock_note(mixed, TOLERANCE) is None
|
||||
assert own_clock_note(agree[:3], TOLERANCE) is None # too few to judge
|
||||
|
||||
|
||||
def test_the_page_lists_managed_nodes_first_then_the_clocks_out_of_sync() -> None:
|
||||
"""A managed node is listed also in sync. An other node is listed only out of sync."""
|
||||
rows = [
|
||||
_row("Hilltop", 10, managed=True),
|
||||
_row("Fine", 20),
|
||||
_row("Slow", -3 * 3600),
|
||||
_row("Worse", -9 * 86400),
|
||||
_row("Bob", -900, keyed=False),
|
||||
]
|
||||
screen = clock_drift_screen(rows, tolerance_s=TOLERANCE)
|
||||
assert screen.title == "Clock drift · 5 nodes · 3 out of sync"
|
||||
text = plain("\n".join(screen.render_body(72)))
|
||||
order = [text.index(s) for s in ("Managed nodes", "Hilltop", "Out of sync", "Worse", "Slow")]
|
||||
assert order == sorted(order), "managed first, then the largest offset first"
|
||||
assert "Fine" not in text
|
||||
assert text.index("Senders with no key") < text.index("Bob")
|
||||
assert "15m behind" in text
|
||||
|
||||
|
||||
def test_a_page_with_nothing_out_of_sync_says_so() -> None:
|
||||
"""The Out of sync section always has its heading, and an empty state when it is empty."""
|
||||
screen = clock_drift_screen([_row("Fine", 20)], tolerance_s=TOLERANCE)
|
||||
assert "no other clock is out of sync" in plain("\n".join(screen.render_body(72)))
|
||||
|
||||
|
||||
def test_the_cli_listing_gives_signed_seconds_and_words() -> None:
|
||||
"""The plain face says how far and which way. The document gives signed seconds."""
|
||||
listing = _listing([_row("Fine", 20), _row("Slow", -3 * 3600, managed=True)], TOLERANCE)
|
||||
first, second = listing.rows
|
||||
assert first["offset_s"] == -10800 and first["out_of_sync"] and first["managed"]
|
||||
assert second["offset_s"] == 20 and not second["out_of_sync"]
|
||||
lane = next(c for c in listing.columns if c.key == "offset_s").lanes[0]
|
||||
assert lane.render(first["offset_s"]) == "3h behind"
|
||||
assert lane.render(second["offset_s"]) == "in sync"
|
||||
|
||||
|
||||
class _DevState:
|
||||
def __init__(self, contacts: list[Contact]) -> None:
|
||||
self._contacts = contacts
|
||||
|
||||
async def contacts(self) -> list[Contact]:
|
||||
return self._contacts
|
||||
|
||||
async def self_info(self) -> dict:
|
||||
return {"public_key": "99" * 32}
|
||||
|
||||
|
||||
class _Ctx:
|
||||
def __init__(self, repo: Repository, contacts: list[Contact], admin: AdminStore) -> None:
|
||||
self.repo = repo
|
||||
self.devstate = _DevState(contacts)
|
||||
self.preferences = Preferences()
|
||||
self.admin_store = admin
|
||||
self.log = logging.getLogger("test.clocks")
|
||||
|
||||
|
||||
def test_clock_rows_name_their_nodes_and_mark_the_managed_ones(tmp_path: Path) -> None:
|
||||
"""A DM sender that is a contact gets its contact. A managed one is marked."""
|
||||
repo = Repository(tmp_path / "clocks.db")
|
||||
now = utcnow()
|
||||
repeater = Contact(name="Hilltop", public_key="ab" * 32, node_type=NODE_TYPE_REPEATER)
|
||||
for sender in (repeater.public_key[:12], "cd" * 6):
|
||||
repo.record_chat_message(
|
||||
ChatMessage.from_message(
|
||||
Message(
|
||||
text="hi",
|
||||
sender=sender,
|
||||
sender_timestamp=now - timedelta(hours=2),
|
||||
received_at=now,
|
||||
)
|
||||
)
|
||||
)
|
||||
admin = AdminStore(tmp_path / "admin.json")
|
||||
admin.remember(repeater, "secret")
|
||||
rows = asyncio.run(clock_rows(_Ctx(repo, [repeater], admin)))
|
||||
by_name = {r.name or r.offset.who: r for r in rows}
|
||||
assert by_name["Hilltop"].managed and by_name["Hilltop"].contact is repeater
|
||||
stranger = by_name["cd" * 6]
|
||||
assert not stranger.managed and stranger.contact is not None # a page to open
|
||||
assert stranger.contact.key_prefix == "cd" * 6
|
||||
repo.close()
|
||||
@@ -1764,8 +1764,41 @@ def _links_qr(cols: int, rows: int) -> Screen:
|
||||
)
|
||||
|
||||
|
||||
def _clock_drift(cols: int, rows: int) -> Screen:
|
||||
"""The Clock drift page in its fullest form: a managed node, nodes out of sync, a name.
|
||||
|
||||
The offsets cover each side of the histogram, the longest offset text (``11h 59m
|
||||
behind``), and a long name, so that the lanes meet the edge on each platform.
|
||||
"""
|
||||
from datetime import timedelta
|
||||
|
||||
from meshterm.core.models import NODE_TYPE_CHAT, NODE_TYPE_REPEATER
|
||||
from meshterm.services.clock_offsets import ClockOffset
|
||||
from meshterm.ui.clocks_screen import ClockRow, clock_drift_screen
|
||||
|
||||
now = utcnow()
|
||||
|
||||
def row(name, key, offset_s, *, node_type=NODE_TYPE_CHAT, managed=False, keyed=True): # noqa: ANN001, ANN202
|
||||
who = key[:12] if keyed else name
|
||||
offset = ClockOffset(who, keyed, offset_s, 6, now - timedelta(minutes=40))
|
||||
contact = Contact(name=name, public_key=key, node_type=node_type) if keyed else None
|
||||
return ClockRow(offset, name, key if keyed else None, node_type, managed, contact)
|
||||
|
||||
rows_ = [
|
||||
row("Hilltop-Repeater", _HUB_KEY, 12, node_type=NODE_TYPE_REPEATER, managed=True),
|
||||
row("A Rather Long Repeater Name For Width", "ab" * 32, -(11 * 3600 + 59 * 60)),
|
||||
row("klkdeck", "cd" * 32, -(4 * 86400 + 6 * 3600)),
|
||||
row("NONAME", "ef" * 32, -(3 * 365 * 86400)),
|
||||
row("JRTx", "12" * 32, 54),
|
||||
row("Raphael's T-Deck", "34" * 32, 2 * 3600),
|
||||
row("Bob", "", -900, keyed=False),
|
||||
]
|
||||
return clock_drift_screen(rows_, tolerance_s=300)
|
||||
|
||||
|
||||
_ENTRIES: list[_Entry] = [
|
||||
_Entry("dashboard", _dashboard),
|
||||
_Entry("clock_drift", _clock_drift),
|
||||
_Entry("dashboard-scoped", _dashboard_scoped),
|
||||
_Entry("contacts", _contacts),
|
||||
_Entry("archive_ladder", _archive_ladder),
|
||||
|
||||
+1
-1
@@ -202,7 +202,7 @@ def test_main_menu_sections_answer_the_menus_own_question() -> None:
|
||||
assert list(sections) == _CATEGORY_ORDER # all_tools already sorts them in this order
|
||||
assert sections == {
|
||||
"Message": ["chat", "channels", "rooms", "courier", "contacts"],
|
||||
"Watch": ["dashboard", "livefeed", "watchtower", "timemachine"],
|
||||
"Watch": ["dashboard", "livefeed", "watchtower", "clocks", "timemachine"],
|
||||
"Explore": ["map", "walk", "trace", "trace-path", "records"],
|
||||
"This node": ["info", "config", "advert"],
|
||||
"Other nodes": ["repeater-admin", "tx-optimize"],
|
||||
|
||||
Reference in new issue
Block a user