Source code for fleetmesh_node.planes.operations.updates.core

"""The compartment. Optional; `"updates": true` in config.json turns it on."""
from __future__ import annotations

from typing import Any, Callable, Mapping, Optional, Sequence

from fleetmesh_node import channels as ch_mod
from fleetmesh_node import metrics as mx_mod
from fleetmesh_node import release as release_mod
from fleetmesh_node.compartment import stores as st
from fleetmesh_node.protocols.nostr import client as relay_mod
from fleetmesh_node.config import UpdatesConfig
from fleetmesh_node.config.parameter import Parameter
from fleetmesh_node.interfaces import NostrEvent
from fleetmesh_node.compartment import Command, Compartment, Every, Need
from fleetmesh_core.peering.release import RELEASE_KIND, REVOKE_KIND, ReleaseInfo, parse_revocation, select
from .store import UpdateStore


from .types import UpdateStateReport


Fetcher = Callable[[Sequence[str], Sequence[Mapping[str, Any]]], list[NostrEvent]]


def _relay_fetch(urls: Sequence[str], filters: Sequence[Mapping[str, Any]]) -> list[NostrEvent]:
    return relay_mod.query_all(urls, filters, timeout=10.0)


RELEASE_AVAILABLE: str = 'release.available'
RELEASE_REVOKED: str = 'release.revoked'


[docs]class Updates(Compartment): """Check-and-report: the newest release this node could run, said once. `trouble()` speaks when a newer release is within what the operator's policy would apply - which in this tier is never, so it speaks about any newer compatible patch or minor and stays quiet about a major: an operator who chose `pinned` is told what they could move to without a protocol or API change, not shouted at about a jump they would have to opt into. `updates.ack <version>` silences one version; a newer one speaks again. """ name = 'updates' optional = True enabled_by = 'updates' reads = ('updates', 'relays') live = ('updates',) config_cls = UpdatesConfig SCHEMA = UpdateStore.SCHEMA STORE_CLS = UpdateStore NEEDS = ( Need('db_path', path='updates.sqlite'), Need('cfg', block=UpdatesConfig, getter=True), Need('relays', 'relays'), ) STORES = ( st.Store(key='releases', description='recent release announcements seen', kind=st.RING, shape=dict, bound=256), ) # What this compartment measures. A counter naming a channel is fed by # that channel being raised, so the line and the count come from one # declaration and cannot disagree. METRICS = ( mx_mod.Metric( name='release_available', description='Times a newer compatible release was announced by this node.', kind=mx_mod.COUNTER, counts=RELEASE_AVAILABLE, tags=('updates', 'release')), mx_mod.Metric( name='release_revoked', description='Times a release this node could run was found revoked.', kind=mx_mod.COUNTER, counts=RELEASE_REVOKED, tags=('updates', 'release')), mx_mod.Metric( name='updates_check', description='How long a release check took, end to end.', kind=mx_mod.HISTOGRAM, unit='seconds', buckets=mx_mod.LATENCY_BUCKETS, tags=('updates', 'latency')), ) # Channel names as constants, not strings at the raise site. A mistyped # string is an undeclared channel found at runtime by a counter; a # mistyped constant is a NameError at import. eventbus.py's TOPIC_* names # already work this way. RELEASE_AVAILABLE: str = 'release.available' RELEASE_REVOKED: str = 'release.revoked' # What this compartment says. Before this the same event left as an # unnamed positional tuple - ('release', 'available', version, kind) - # which control.py joined with spaces for the journal and nothing # structured ever saw. The tuple still goes back from tick(); the channel # is what gives it a name, a level and one rendering per audience. CHANNELS = ( ch_mod.Channel( name=RELEASE_AVAILABLE, description='A release newer than the one this node runs is published and ' 'compatible with the operator policy. Said once per version; ' '`updates.ack <version>` silences one.', level=ch_mod.NOTE, wire=lambda version, kind, running: { 'version': version, 'kind': kind, 'running': running}, say='release {version} available ({kind}) - running {running}', tags=('updates', 'release')), ch_mod.Channel( name=RELEASE_REVOKED, description='A release this node could run was revoked by the signing key. ' 'Trouble rather than a note: a revoked release is one nobody ' 'should move to.', level=ch_mod.TROUBLE, wire=lambda version, reason: {'version': version, 'reason': reason}, say='release {version} revoked: {reason}', tags=('updates', 'release', 'trouble')), ) COMMANDS = ( Command( key='check', name='Check Updates', description='ask the channel now; the state after', tags=('updates', 'check'), permission='updates/check', run='check', reply='dict', ), Command( key='show', name='Updates Status', description='the newest compatible release as parsed, and every one seen', tags=('updates', 'status'), permission='updates/show', run='show_cmd', reply='dict', ), Command( key='ack', name='Acknowledge Update', description='stop mentioning this version in trouble', tags=('updates', 'ack'), parameters=( Parameter(key='version', name='version', description='semver version to acknowledge', type=str, default='', required=True), ), permission='updates/ack', run='ack_cmd', reply='dict', ), ) EVERY = ( Every( # 0 is off (Every.is_off): checked only on command. seconds=lambda self: float(max(0, self.settings().check_every)), run='periodic_check', name='check_updates', ), )
[docs] def __init__( self, db_path: str = ':memory:', cfg: Optional[Callable[[], UpdatesConfig]] = None, relays: Optional[Sequence[str]] = None, clock: Optional[Callable[[], int]] = None, fetch: Fetcher = _relay_fetch, running: Optional[release_mod.Release] = None, node: Any = None, db: Optional[Any] = None, ) -> None: if db is not None: if not isinstance(db, UpdateStore): # Said here, by name, rather than as an AttributeError on the # first store method - which is how B13 went unnoticed. raise TypeError('updates needs an UpdateStore as db, not %s' % type(db).__name__) store: Any = db elif db_path: store = UpdateStore(db_path) else: store = UpdateStore(':memory:') super().__init__(node, clock, db=store) self.store: Any = store self.db = store self._cfg: Callable[[], UpdatesConfig] = cfg or (lambda: UpdatesConfig()) self._relays: list[str] = list(relays or []) # not a store: the configured relays self._fetch = fetch self.running: release_mod.Release = running or release_mod.running() self.newest: Optional[ReleaseInfo] = None # newest compatible, newer than running self.incompatible: Optional[ReleaseInfo] = None # newest that speaks another protocol self._closed = False last = self.store.last_check() if last is not None: self._every_last['check_updates'] = last
# ---- configuration ----------------------------------------------------------------
[docs] def settings(self) -> UpdatesConfig: return self._cfg()
[docs] def channel(self) -> list[str]: return list(self.settings().channel) or self._relays
[docs] def version(self) -> str: """What this node runs, by the operator's word if they gave one.""" return self.settings().pinned or self.running.version
[docs] def policy_for(self, compartment: str = '*') -> str: pol = self.settings().policy return str(pol.get(compartment) or pol.get('*') or 'pinned')
# ---- the check ----------------------------------------------------------------------
[docs] def check(self, now: Optional[int] = None) -> UpdateStateReport: now = self.clock() if now is None else now s = self.settings() urls = self.channel() # kind + author only: relays index single-letter tags (NIP-01), so a # `#name` filter matches nothing anywhere. parse_release_event keeps # the name check; releases of other packages are skipped, not counted. filters = [{'kinds': [RELEASE_KIND, REVOKE_KIND], 'authors': [s.release_key], 'limit': 100}] reachable: dict[str, bool] = {} events: list[NostrEvent] = [] for url in urls: try: events.extend(self._fetch([url], filters)) reachable[url] = True except Exception as e: # a relay down is state, not a crash reachable[url] = False self.refusals.refuse('channel', 'unreachable', subject=url, detail={'error': str(e)[:120]}, at=now) # the pure half - revocations first whichever order relays hand # events back, then the newest compatible / incompatible newer - # is fleetmesh_core.peering.release.select, the rule the conformance vectors pin sel = select(events, s.release_key, self.version(), self.running.protocol, self.running.name, already_revoked=self.store.revoked()) for ev in events: rv = parse_revocation(ev, s.release_key) if rv is not None: self.store.revoke(rv[0], rv[1], now) for eid, why in sel.refused: self.refusals.refuse('release', why, subject=eid[:16], at=now) revoked = set(sel.revoked) # a revocation can arrive after the release was already the newest; # a previous check's pick stays unless this check found a newer one newest = None if self.newest and self.newest.event_id in revoked else self.newest incompatible = None if self.incompatible and self.incompatible.event_id in revoked else self.incompatible if sel.newest_compatible and (newest is None or release_mod.compare(sel.newest_compatible.version, newest.version) > 0): newest = sel.newest_compatible if sel.incompatible_newer and (incompatible is None or release_mod.compare(sel.incompatible_newer.version, incompatible.version) > 0): incompatible = sel.incompatible_newer self.newest, self.incompatible = newest, incompatible if newest is not None: self.store.saw(newest.version, newest.event_id, newest.sha256, now) self.store.checked(now, reachable) return self.state()
[docs] def periodic_check(self, now: int) -> list[tuple[Any, ...]]: if self.settings().check_every <= 0: return [] before = self.newest.version if self.newest else None self.check(now) after = self.newest.version if self.newest else None return [('release', 'available', after, release_mod.classify(self.version(), after))] if after and after != before else []
# ---- the compartment contract ---------------------------------------------------------------
[docs] def state(self) -> UpdateStateReport: if self._closed: return {'stopped': True} n = self.newest cfg = self.settings() # parsed once, not three times (audit E7) return { 'running': dict(self.running.as_dict(), pinned=cfg.pinned), 'release_key': cfg.release_key, 'policy': dict(cfg.policy), 'channel': self.channel(), 'reachable': self.store.reachable(), 'last_check': self.store.last_check(), 'newest_compatible': dict(n.as_dict(), **{'class': release_mod.classify(self.version(), n.version), 'acked': self.store.acked(n.version)}) if n else None, 'incompatible_newer': self.incompatible.as_dict() if self.incompatible else None, 'revoked': self.store.revoked(), }
[docs] def trouble(self) -> list[str]: out: list[str] = [] n = self.newest if n is not None and not self.store.acked(n.version): cls = release_mod.classify(self.version(), n.version) if cls in ('patch', 'minor'): out.append('%s %s available (%s); you run %s; policy %s - `meshnode updates.show` for the release' % (n.name, n.version, cls, self.version(), self.policy_for())) if self.running.source == 'checkout' and n is not None and not self.store.acked(n.version): out.append('this node runs from a checkout; updates are reported, never applied here') reach = self.store.reachable() if reach and not any(reach.values()): out.append('update channel unreachable: %s' % ', '.join(sorted(reach))) return out
[docs] def show_cmd(self) -> Mapping[str, Any]: return {'newest_compatible': self.newest.as_dict() if self.newest else None, 'incompatible_newer': self.incompatible.as_dict() if self.incompatible else None, 'seen': self.store.seen(), 'revoked': self.store.revoked()}
[docs] def ack_cmd(self, args: Mapping[str, Any]) -> Mapping[str, Any]: v = str(args.get('version', '')) if release_mod.parse_semver(v) is None: raise ValueError('updates.ack: version must be a semver') return {'version': v, 'acked': self.store.ack(v)}
[docs] def stop(self) -> Any: self._closed = True self.store.close() super().stop() return None