Files
MeshTerm/meshterm/services/clock_offsets.py
T
Jean-Pierre MartineauandClaude Haiku 5.5 e830f2239d A room whose clock went back can be asked for all its posts again
A room stamps posts with its own clock and sends only posts newer than
the companion's sync_since, so after its clock goes back (often a
reboot) it sends nothing new. When a room's newest stored post is later
than its clock now (from its clock offset), its node page shows
"posts  blocked" and offers "Ask for all its posts again…". The repair
removes the room contact and adds the same raw record back, since the
firmware gives only a new contact a sync_since of zero, then logs in
with the stored password. Device.reset_room_sync tries the add twice and
says plainly if the room is left off the device.

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

219 lines
8.4 KiB
Python

# SPDX-License-Identifier: Apache-2.0
"""How far the clock of each node is from ours, measured from what it sent us.
Each packet that carries the time of its sender, and that we heard at a known time, is one
**clock sample**: the sender time minus our time. A packet takes only seconds to cross the
mesh, so the sample is the error of the sender's clock. Three kinds of packet give one:
* **An advert.** It carries the time when its node made it, and the RX log gives our time
(``observations.sent_at`` and ``observed_at``). It has a key, so the sample belongs to a
node with no doubt. Each type of node sends adverts, repeaters too.
* **A direct message**, by its sender time and its arrival time. It comes from a known key
prefix.
* **A channel message.** It has no sender field, only the ``Name: `` prefix of its text.
A name that resolves to exactly one key (refer to
:func:`~meshterm.services.trace_runner.make_name_key_resolver`) gives a sample for that
node. Each other name is a **sender with no key**, and its samples stay under the name.
A room post is not a sample: its time is when its author posted it. A message that waited
in the companion is not a sample: its arrival time is not known.
The **offset** of a node is the median of its three newest samples. Thus one wrong sample
has no effect, and when the owner sets the clock, the offset follows after two new samples.
"""
from __future__ import annotations
import statistics
from collections.abc import Callable, Iterable
from dataclasses import dataclass
from datetime import datetime, timedelta
from typing import TYPE_CHECKING
from ..core.channels import split_channel_sender
from ..core.models import utcnow
if TYPE_CHECKING:
from ..persistence.repository import Repository
#: The number of the newest samples whose median is the offset of a node.
NEWEST = 3
#: Resolves a channel sender name to the key of its node, or ``None``.
KeyOf = Callable[[str], "str | None"]
@dataclass(frozen=True, slots=True)
class ClockSample:
"""One packet with the time of its sender and our time of arrival.
Attributes:
who: The 12-hex id of the node, or the sender name when :attr:`keyed` is false.
keyed: Whether a key identifies the sender.
sent_at: The time by the clock of the sender.
arrived_at: The time by our clock.
"""
who: str
keyed: bool
sent_at: datetime
arrived_at: datetime
@property
def offset_s(self) -> float:
"""The sender time minus our time, in seconds. Positive is a clock ahead of ours."""
return (self.sent_at - self.arrived_at).total_seconds()
@dataclass(frozen=True, slots=True)
class ClockOffset:
"""How far the clock of one node (or one sender with no key) is from ours.
Attributes:
who: The 12-hex id of the node, or the sender name when :attr:`keyed` is false.
keyed: Whether a key identifies the sender.
offset_s: The median of the newest :data:`NEWEST` samples, in seconds. Positive is
a clock ahead of ours.
samples: The number of samples in all.
last_at: Our time of the newest sample.
"""
who: str
keyed: bool
offset_s: float
samples: int
last_at: datetime
def out_of_sync(self, tolerance_s: float) -> bool:
"""Whether the clock is farther from ours than the ``clock_tolerance_s`` preference."""
return abs(self.offset_s) > tolerance_s
def offsets(samples: Iterable[ClockSample]) -> list[ClockOffset]:
"""Make one offset for each sender from its samples.
Args:
samples: The samples, in any order.
Returns:
One :class:`ClockOffset` for each sender, in no specific order.
"""
groups: dict[tuple[str, bool], list[ClockSample]] = {}
for sample in samples:
groups.setdefault((sample.who, sample.keyed), []).append(sample)
result = []
for (who, keyed), group in groups.items():
group.sort(key=lambda s: s.arrived_at)
newest = group[-NEWEST:]
result.append(
ClockOffset(
who=who,
keyed=keyed,
offset_s=float(statistics.median(s.offset_s for s in newest)),
samples=len(group),
last_at=newest[-1].arrived_at,
)
)
return result
def _channel_sample(
text: str, sent: datetime, arrived: datetime, key_of: KeyOf | None
) -> ClockSample | None:
"""The sample of one channel message, under its node or under its sender name."""
name, _body = split_channel_sender(text)
if not name:
return None # no prefix: nobody to give the sample to
key = key_of(name) if key_of is not None else None
if key:
return ClockSample(key.lower().removeprefix("0x")[:12], True, sent, arrived)
return ClockSample(name, False, sent, arrived)
def window_samples(
repo: Repository, *, since: datetime | None, key_of: KeyOf | None
) -> list[ClockSample]:
"""All the clock samples that arrived since a time, from adverts and messages.
Args:
repo: The repository that holds the packet log and the messages.
since: The start of the window, or ``None`` for all the history.
key_of: Resolves a channel sender name to a key.
Returns:
The samples, oldest first within each source.
"""
samples = [
ClockSample(node, True, sent, heard)
for node, sent, heard in repo.advert_clock_samples(since=since)
]
for is_channel, peer, text, sent, arrived in repo.message_clock_samples(since=since):
if is_channel:
sample = _channel_sample(text, sent, arrived, key_of)
if sample is not None:
samples.append(sample)
elif peer:
samples.append(ClockSample(peer.lower()[:12], True, sent, arrived))
return samples
def room_posts_blocked(
newest_post: datetime | None, offset: ClockOffset | None, tolerance_s: float
) -> bool:
"""Whether a room can no longer send us its new posts, because its clock went back.
A room stamps each post with its own clock. The companion asks for the posts newer than
the newest one that it got (its ``sync_since``), and the room sends only those
(``post_timestamp > sync_since`` in the room firmware). When the clock of the room goes
back, for example after a reboot with no clock source, each new post is older than
that time, and the room never sends it. The room keeps its posts only in memory, so a
reboot also loses the old ones.
Args:
newest_post: The newest post time that we stored for the room (its clock).
offset: The clock offset of the room now, from its adverts and replies.
tolerance_s: The ``clock_tolerance_s`` preference.
Returns:
``True`` when the newest post is later than the clock of the room now, by more than
the tolerance. ``False`` when that is not so, or when a value is not known.
"""
if newest_post is None or offset is None:
return False
room_now = utcnow() + timedelta(seconds=offset.offset_s)
return newest_post > room_now + timedelta(seconds=tolerance_s)
def node_offset(
repo: Repository, node: str, *, name: str | None = None, key_of: KeyOf | None = None
) -> ClockOffset | None:
"""The clock offset of one node, from all its history.
Args:
repo: The repository that holds the packet log and the messages.
node: The key of the node, or its 12-hex id.
name: The name of the node. Its channel messages count only when ``key_of``
resolves this name to this node, because another node can use the same name.
key_of: Resolves a channel sender name to a key.
Returns:
The offset, or ``None`` when no packet of the node carried a usable time.
"""
node_id = node.lower().removeprefix("0x")[:12]
samples = [
ClockSample(node_id, True, sent, heard)
for _node, sent, heard in repo.advert_clock_samples(node=node_id)
]
samples += [
ClockSample(node_id, True, sent, arrived)
for _chan, _peer, _text, sent, arrived in repo.message_clock_samples(peer=node_id)
]
resolved = key_of(name) if (name and key_of is not None) else None
if name and resolved and resolved.lower().removeprefix("0x")[:12] == node_id:
samples += [
ClockSample(node_id, True, sent, arrived)
for _chan, _peer, _text, sent, arrived in repo.message_clock_samples(sender=name)
]
found = offsets(samples)
return found[0] if found else None