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