"""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