fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/operations/updates/core.py

@@ -0,0 +1,310 @@
+"""The compartment. Optional; `"updates": true` in config.json turns it on."""
+from __future__ import annotations
+
+from typing import Any, Callable, Mapping, Optional, Sequence
+
+from node import channels as ch_mod
+from node import metrics as mx_mod
+from node import release as release_mod
+from node.compartment import stores as st
+from node.protocols.nostr import client as relay_mod
+from node.config import UpdatesConfig
+from node.config.parameter import Parameter
+from node.interfaces import NostrEvent
+from 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'
+
+
+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',
+        ),
+    )
+
+    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 ----------------------------------------------------------------
+    def settings(self) -> UpdatesConfig:
+        return self._cfg()
+
+    def channel(self) -> list[str]:
+        return list(self.settings().channel) or self._relays
+
+    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
+
+    def policy_for(self, compartment: str = '*') -> str:
+        pol = self.settings().policy
+        return str(pol.get(compartment) or pol.get('*') or 'pinned')
+
+    # ---- the check ----------------------------------------------------------------------
+    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()
+
+    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 ---------------------------------------------------------------
+    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(),
+        }
+
+    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
+
+    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()}
+
+    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)}
+
+    def stop(self) -> Any:
+        self._closed = True
+        self.store.close()
+        super().stop()
+        return None

node/planes/operations/updates/store.py

@@ -0,0 +1,79 @@
+"""What the update check has seen and what the operator has acknowledged.
+
+Durable so a restart does not re-announce a release the operator already
+read, and so `last_check` survives to be reported honestly.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Mapping, Optional
+
+from node.compartment.schema import Column, Table
+from node.storage import SqliteStore
+
+
+class UpdateStore(SqliteStore):
+    SCHEMA = (
+        Table('kv', (
+            Column('k', 'TEXT', primary_key=True),
+            Column('v', 'TEXT', not_null=True),
+        )),
+        Table('seen', (
+            Column('version', 'TEXT', primary_key=True),
+            Column('event_id', 'TEXT', not_null=True),
+            Column('sha256', 'TEXT', not_null=True),
+            Column('first_seen', 'INTEGER', not_null=True),
+            Column('acked', 'INTEGER', not_null=True, default=0),
+        )),
+        Table('revoked', (
+            Column('event_id', 'TEXT', primary_key=True),
+            Column('reason', 'TEXT', not_null=True),
+            Column('seen', 'INTEGER', not_null=True),
+        )),
+    )
+
+    def _get(self, k: str) -> Optional[Any]:
+        row = self._one('SELECT v FROM kv WHERE k=?', (k,))
+        return json.loads(row[0]) if row else None
+
+    def _set(self, k: str, v: Any) -> None:
+        with self.transaction() as cur:
+            cur.execute('INSERT OR REPLACE INTO kv (k, v) VALUES (?, ?)', (k, json.dumps(v)))
+
+    def last_check(self) -> Optional[int]:
+        v = self._get('last_check')
+        return int(v) if v is not None else None
+
+    def checked(self, now: int, reachable: dict[str, bool]) -> None:
+        self._set('last_check', now)
+        self._set('reachable', reachable)
+
+    def reachable(self) -> dict[str, bool]:
+        return dict(self._get('reachable') or {})
+
+    def saw(self, version: str, event_id: str, sha256: str, now: int) -> bool:
+        """Record a release; True if this is the first time."""
+        with self.transaction() as cur:
+            cur.execute('INSERT OR IGNORE INTO seen (version, event_id, sha256, first_seen) VALUES (?,?,?,?)',
+                        (version, event_id, sha256, now))
+            return cur.rowcount == 1
+
+    def ack(self, version: str) -> bool:
+        with self.transaction() as cur:
+            cur.execute('UPDATE seen SET acked=1 WHERE version=?', (version,))
+            return cur.rowcount == 1
+
+    def acked(self, version: str) -> bool:
+        row = self._one('SELECT acked FROM seen WHERE version=?', (version,))
+        return bool(row and row[0])
+
+    def seen(self) -> list[Mapping[str, Any]]:
+        rows = self._all('SELECT version, event_id, sha256, first_seen, acked FROM seen ORDER BY first_seen')
+        return [dict(version=r[0], event_id=r[1], sha256=r[2], first_seen=r[3], acked=bool(r[4])) for r in rows]
+
+    def revoke(self, event_id: str, reason: str, now: int) -> None:
+        with self.transaction() as cur:
+            cur.execute('INSERT OR IGNORE INTO revoked (event_id, reason, seen) VALUES (?,?,?)', (event_id, reason, now))
+
+    def revoked(self) -> dict[str, str]:
+        return {r[0]: r[1] for r in self._all('SELECT event_id, reason FROM revoked')}

node/planes/operations/updates/types.py

@@ -0,0 +1,20 @@
+"""Types and records for the Updates compartment."""
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional, TypedDict
+
+from fleetmesh_core.peering.release import ReleaseDict
+
+
+class UpdateStateReport(TypedDict, total=False):
+    """The report Updates.state() gives of itself."""
+    stopped: bool
+    running: Mapping[str, Any]
+    release_key: str
+    policy: Mapping[str, str]
+    channel: list[str]
+    reachable: Mapping[str, bool]
+    last_check: Optional[int]
+    newest_compatible: Optional[Mapping[str, Any]]
+    incompatible_newer: Optional[ReleaseDict]
+    revoked: list[str]

node/planes/peering/__init__.py

@@ -0,0 +1,28 @@
+"""Peering plane: trust, strain, peering, budget, capacity, reporter."""
+from . import budget, capacity, peering, reporter, strain, trust
+from .budget.core import Budget, BudgetConfig
+from .capacity.compartment import Capacity
+from .peering.core import Peering, PolicyConfig
+from .reporter.core import Reporter, ReporterConfig
+from .strain.compartment import StrainConfig, StrainLedger
+from .trust.compartment import Trust, TrustConfig
+
+__all__ = [
+    'Budget',
+    'BudgetConfig',
+    'Capacity',
+    'Peering',
+    'PolicyConfig',
+    'Reporter',
+    'ReporterConfig',
+    'StrainConfig',
+    'StrainLedger',
+    'Trust',
+    'TrustConfig',
+    'budget',
+    'capacity',
+    'peering',
+    'reporter',
+    'strain',
+    'trust',
+]

node/planes/peering/budget/__init__.py

@@ -0,0 +1,43 @@
+"""budget/1.0 over the wire, and the window it feeds.
+
+The grant is a promise about what a subject may do to an issuer. Both sides
+count it. The issuer meters what the peer actually did (bytes it sent,
+events it delivered, requests it made); the subject meters the same
+quantities from its own side and states them, cumulatively, in a chained
+receipt on the cadence the grant names. The issuer answers every receipt
+with an ack carrying the head it holds. When a window closes and the grace
+has passed, the issuer evaluates measured against claimed with fleetmesh_core/window.py - under
+the grant that governed that window - and applies the ladder's remedy with
+the reference's AIMD. The grant it decides on waits for the next window
+boundary; there it is written, published as a new kind 30801 under the same
+blinded d tag, and the subject is told with peering/1.0/amend. The standing
+ledger records the window.
+
+The wait is not a nicety. Published the moment the grace period ended, an
+amend landed six minutes into the next window, and a receipt is a statement
+about one window under one grant: the issuer rejected every receipt still
+naming the grant it had just replaced, the subject restarted its chain at
+seq 0 on the one it had just taken up, and every window after the first
+closed on a claim from its first ten minutes. Both nodes filed S2 against an
+honest peer every hour, and one published a kind 30802 about it. A chain is
+per window and survives the grant changing under it; a receipt names the
+grant the subject held when it wrote it, and the issuer accepts the grant
+that governed the window, the one before it, and the one current now.
+
+Every number here is in the issuer's frame, which is the grant's: events_in
+is events into the issuer, bytes_out is bytes the issuer sent. That is the
+frame the specification's tier ceilings are written in and the frame
+fleetmesh_core/badpeer.py measures in.
+"""
+from __future__ import annotations
+from .meter import (  # noqa: E402
+    AMEND, C, KEEP_FINDINGS, METERED, PIURI, SYNC, TOLERANCE, ZERO, Meter, _observe, _ranges, metered_bytes,
+)
+from .core import Budget  # noqa: E402
+from .chain import OutChain  # noqa: E402
+from .evaluation import Evaluation, Repricing  # noqa: E402
+
+__all__ = [
+    'AMEND', 'Budget', 'C', 'Evaluation', 'KEEP_FINDINGS', 'METERED', 'Meter', 'OutChain', 'PIURI', 'Repricing', 'SYNC', 'TOLERANCE', 'ZERO',
+    '_observe', '_ranges', 'metered_bytes',
+]

node/planes/peering/budget/chain.py

@@ -0,0 +1,43 @@
+"""The outbound receipt chain this node keeps per (peer, window).
+
+One per window this node has sent a receipt in. `seq` and `prev` are what
+the next receipt will carry; `heads` is every head this node produced, in
+sequence order, so an ack naming one says how far behind the receiver is;
+`final` marks the chain closed by the window's final receipt. Written to
+the AccountStore before the receipt leaves (node/budget/receipts.py says
+why), and read back whole on restart.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any, Mapping, Optional, cast
+
+from .meter import ZERO
+
+__all__ = ['OutChain', 'OutChainDict']
+
+
+from .types import OutChainDict
+
+
+@dataclass(slots=True)
+class OutChain:
+    grant: str                                  # envelope id of the grant governing the window
+    seq: int = 0
+    prev: str = ZERO                            # the head the first receipt chains from
+    sent_at: Optional[int] = None
+    last: Optional[dict[str, int]] = None       # the counters the latest receipt claimed
+    heads: list[str] = field(default_factory=list)
+    final: bool = False
+
+    def to_dict(self) -> OutChainDict:
+        return cast(OutChainDict, asdict(self))
+
+    @classmethod
+    def from_dict(cls, body: Mapping[str, Any]) -> OutChain:
+        """A chain row as the AccountStore stored it. Rows written before
+        `heads` and `final` were kept read as empty and open."""
+        return cls(grant=body.get('grant') or '', seq=int(body.get('seq', 0)), prev=body.get('prev') or ZERO,
+                   sent_at=body.get('sent_at'), last=body.get('last'),
+                   heads=list(body.get('heads') or []), final=bool(body.get('final', False)))