Source code for fleetmesh_core.peering.release

"""Release channel (operations plane): kind 9900 releases, kind 9901 revocations,
semver order, and which release a running node should mention.

Reused: kind 9900/9901 are npack's release and revocation kinds; a release is
read the way `scripts/sign_release.py` writes it. What fleetmesh adds is the
`provides fleetmesh/<version>@<digest>` tag and the selection rule: among the
releases by the pinned key that verify and name this package, the newest one
newer than what runs and speaking this node's digest is `newest_compatible`;
the newest newer one speaking another digest is `incompatible_newer` -
reported, never installed, because the digest is a reviewed commitment.
"""
from __future__ import annotations

import dataclasses
import re
from typing import Any, Iterable, Mapping, Optional, TypedDict, Union

from ..storage import store

RELEASE_KIND: int = 9900
REVOKE_KIND: int = 9901
PROTOCOL_PREFIX: str = 'fleetmesh/0.1-draft@'
NAME: str = 'fleetmesh-node'
OTHER_PACKAGE: str = 'another package'   # the key's other releases: not ours, not a refusal

SEMVER = re.compile(r'^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$')


[docs]def parse_semver(v: str) -> Optional[tuple[int, int, int, str]]: """(major, minor, patch, prerelease) or None when `v` is not a semver. Surrounding whitespace is tolerated; build metadata (`+...`) is not.""" m = SEMVER.match(str(v).strip()) if not m: return None return int(m.group(1)), int(m.group(2)), int(m.group(3)), m.group(4) or ''
[docs]def compare(a: str, b: str) -> int: """-1, 0, 1 for a <, ==, > b. A prerelease sorts below its release; two prereleases compare as plain strings (not SemVer 2 dotted-identifier order - this is the rule both nodes implement).""" pa, pb = parse_semver(a), parse_semver(b) if pa is None or pb is None: raise ValueError('not a semver: %r' % (a if pa is None else b)) if pa[:3] != pb[:3]: return -1 if pa[:3] < pb[:3] else 1 if pa[3] == pb[3]: return 0 if not pa[3]: return 1 if not pb[3]: return -1 return -1 if pa[3] < pb[3] else 1
[docs]def classify(running: str, candidate: str) -> Optional[str]: """'major', 'minor' or 'patch' when candidate is newer than running; None otherwise.""" if compare(candidate, running) <= 0: return None r, c = parse_semver(running), parse_semver(candidate) assert r is not None and c is not None if c[0] != r[0]: return 'major' if c[1] != r[1]: return 'minor' return 'patch'
[docs]class ReleaseDict(TypedDict): event_id: str signer: str name: str version: str sha256: str artifact_event: Optional[str] protocols: list[str] os: str arch: str created_at: int
[docs]class SelectionDict(TypedDict): newest_compatible: Optional[ReleaseDict] incompatible_newer: Optional[ReleaseDict] refused: list[list[str]] revoked: list[str]
[docs]@dataclasses.dataclass(frozen=True) class ReleaseInfo: event_id: str signer: str name: str version: str sha256: str artifact_event: Optional[str] protocols: tuple[str, ...] # digests from `provides fleetmesh/0.1-draft@<digest>` os: str arch: str created_at: int
[docs] def speaks(self, digest: str) -> bool: return digest in self.protocols
[docs] def as_dict(self) -> ReleaseDict: # JSON-shaped: the control socket and the conformance op reply with this return ReleaseDict(event_id=self.event_id, signer=self.signer, name=self.name, version=self.version, sha256=self.sha256, artifact_event=self.artifact_event, protocols=list(self.protocols), os=self.os, arch=self.arch, created_at=self.created_at)
def _tags(ev: Mapping[str, Any]) -> dict[str, list[list[str]]]: out: dict[str, list[list[str]]] = {} for t in ev.get('tags') or []: if isinstance(t, list) and t and isinstance(t[0], str): out.setdefault(t[0], []).append([str(x) for x in t]) return out
[docs]def parse_revocation(ev: Mapping[str, Any], release_key: str) -> Optional[tuple[str, str]]: """(revoked release event id, reason) for a kind 9901 by the pinned key whose signature verifies; None for anything else. A revocation signed by another key is not a revocation of anything, so it is silently nothing. The reason is the `reason` tag, else the content.""" if ev.get('kind') != REVOKE_KIND or str(ev.get('pubkey', '')).lower() != release_key: return None if not store.verify_event(ev): return None t = _tags(ev) target = t['e'][0][1] if t.get('e') and len(t['e'][0]) > 1 else None if not target: return None reason = t['reason'][0][1] if t.get('reason') and len(t['reason'][0]) > 1 else str(ev.get('content', '')) return target, reason
[docs]def parse_release_event(ev: Mapping[str, Any], release_key: str, name: str = NAME) -> Union[ReleaseInfo, str]: """A ReleaseInfo, or the one-line reason this event is not a release this node will mention. The reasons are refusals the compartment counts: an event under the project's name from another key is a signal. Checks run in this order and the first failure is the reason: kind, key, signature, name (OTHER_PACKAGE - skipped, not counted), version, x, provides.""" if ev.get('kind') != RELEASE_KIND: return 'not a release event (kind %r)' % (ev.get('kind'),) if str(ev.get('pubkey', '')).lower() != release_key: return 'signed by %s, not the pinned release key' % str(ev.get('pubkey', ''))[:16] if not store.verify_event(ev): return 'signature does not verify' t = _tags(ev) one = lambda k: t[k][0][1] if t.get(k) and len(t[k][0]) > 1 else None # noqa: E731 if one('name') != name: return OTHER_PACKAGE version = one('version') if version is None or parse_semver(version) is None: return 'version %r is not a semver' % (version,) sha = one('x') if sha is None or len(sha) != 64: return 'no artefact hash (x tag)' protocols = tuple(p[1][len(PROTOCOL_PREFIX):] for p in t.get('provides', []) if len(p) > 1 and p[1].startswith(PROTOCOL_PREFIX)) if not protocols: return 'declares no fleetmesh protocol (provides tag)' return ReleaseInfo(event_id=str(ev['id']), signer=release_key, name=name, version=version, sha256=sha.lower(), artifact_event=one('artifact'), protocols=protocols, os=one('os') or 'any', arch=one('arch') or 'any', created_at=int(ev.get('created_at', 0)))
[docs]@dataclasses.dataclass(frozen=True) class Selection: newest_compatible: Optional[ReleaseInfo] incompatible_newer: Optional[ReleaseInfo] refused: tuple[tuple[str, str], ...] # (event id, reason) - what the compartment counts revoked: tuple[str, ...] # release ids a verified 9901 withdrew
[docs] def as_dict(self) -> SelectionDict: return SelectionDict(newest_compatible=self.newest_compatible.as_dict() if self.newest_compatible else None, incompatible_newer=self.incompatible_newer.as_dict() if self.incompatible_newer else None, refused=[list(r) for r in self.refused], revoked=list(self.revoked))
[docs]def select(events: Iterable[Mapping[str, Any]], release_key: str, running: str, digest: str, name: str = NAME, already_revoked: Iterable[str] = ()) -> Selection: """The pure half of an update check. Revocations are applied first whatever order the relays hand events back in; a revoked release is skipped silently. Releases not newer than `running` are skipped. Among the rest, the newest speaking `digest` is newest_compatible; the newest speaking anything else is incompatible_newer. Ties on version go to the first seen (compare > 0 to replace).""" evs = list(events) revoked: dict[str, str] = {} for ev in evs: rv = parse_revocation(ev, release_key) if rv is not None: revoked.setdefault(rv[0], rv[1]) gone = set(already_revoked) | set(revoked) newest: Optional[ReleaseInfo] = None incompatible: Optional[ReleaseInfo] = None refused: list[tuple[str, str]] = [] for ev in evs: if ev.get('kind') != RELEASE_KIND: continue if str(ev.get('id', '')) in gone: continue r = parse_release_event(ev, release_key, name) if r == OTHER_PACKAGE: continue if isinstance(r, str): refused.append((str(ev.get('id', '')), r)) continue if compare(r.version, running) <= 0: continue if not r.speaks(digest): if incompatible is None or compare(r.version, incompatible.version) > 0: incompatible = r continue if newest is None or compare(r.version, newest.version) > 0: newest = r return Selection(newest, incompatible, tuple(refused), tuple(sorted(gone)))