fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/identity/discovery/compartment.py

@@ -0,0 +1,522 @@
+"""What this node tells the mesh it is and what it holds, as a compartment.
+
+Two publications with one shape: a kind 30166 per endpoint for NIP-66 readers,
+and a kind 30803 per shard for anything looking for data rather than for nodes.
+Both are addressable, both are republished only when what they say changes, and
+both can be refused - a discovery event that contradicts the descriptor, a
+coverage claim a leaf may not make.
+
+Those refusals went into the tick's return value and nowhere else. `coverage
+claim refused` was printed once and then gone: an operator who had added a shard
+to the config and never saw it claimed had the reason in a journal line that had
+already scrolled, and nothing to ask.
+
+The forward clock lives here because both of these are addressable events under
+a stable `d`, and so is the report the reporter publishes, which borrows it.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, Mapping, MutableMapping, Optional, Sequence
+
+import dataclasses
+from fleetmesh_core.peering import coverage
+from fleetmesh_core.services import discovery as ref_discovery
+from fleetmesh_core.storage import store as ref_store
+from fleetmesh_core.wire.wire_types import HandoverLink
+from node.compartment import stores as st
+from node.channels import Channel, NOTE, TROUBLE
+from node.metrics import COUNTER, Metric
+from node.protocols.nostr import client as relay
+from node.planes.store.sync import rules as handover
+from node.planes.store.sync.rules import CoverageShardConfig
+from node.interfaces import NostrEvent
+from node.compartment import Command, Compartment, Every, Need
+from node.config.parameter import Parameter, ParamBlock
+
+
+from .types import DiscoveryStateReport
+
+
+def _range_of(claim: NostrEvent) -> tuple[Optional[str], Optional[str]]:
+    """The (since, until) a kind 30803 declares, as tagged."""
+    tags = {t[0]: t[1] for t in claim['tags'] if len(t) > 1 and t[0] in ('since', 'until')}
+    return tags.get('since'), tags.get('until')
+
+
+@dataclasses.dataclass(frozen=True)
+class DiscoveryConfig(ParamBlock):
+    key = 'discovery'
+    name = 'discovery'
+    DERIVED: bool = False
+    PARAMS = (
+        Parameter(
+            key='coverage_interval', name='Coverage Publication Interval',
+            description='Seconds between coverage claim publications',
+            type=int, default=60, minimum=10,
+            tags=('discovery', 'coverage'),
+        ),
+        Parameter(
+            key='discovery_interval', name='Discovery Publication Interval',
+            description='Seconds between discovery endpoint publications',
+            type=int, default=300, minimum=30,
+            tags=('discovery', 'announcement'),
+        ),
+    )
+    coverage_interval: int = 60
+    discovery_interval: int = 300
+
+
+class Discovery(Compartment):
+    requires: tuple[str, ...] = ('capacity',)
+
+    name: str = 'discovery'
+    reads: tuple[str, ...] = ('coverage', 'class')
+    config_cls = DiscoveryConfig
+    live: tuple[str, ...] = ('coverage',)
+    CHANNELS = (
+        Channel('coverage_narrowed', 'Coverage claim narrowed under capacity pressure', level=NOTE,
+                say='shard {shard} is no longer claimed while this node sheds: it is held through the mesh and the node is at its ceiling'),
+        Channel('coverage_downgraded', 'Coverage completeness downgraded to best-effort', level=NOTE,
+                say='shard {shard} is claimed best-effort, not asserted: some of it arrived through the mesh and this node cannot stand behind it'),
+        Channel('handover_dropped', 'Handover chain dropped for shard', level=TROUBLE,
+                say='shard {shard} handover from {from_peer} dropped: {why}'),
+    )
+    METRICS = (
+        Metric(name='discovery_coverage_narrowed', description='Times coverage claims were narrowed.',
+               kind=COUNTER, counts='coverage_narrowed', tags=('discovery', 'coverage')),
+        Metric(name='discovery_coverage_downgraded', description='Times coverage claims were downgraded.',
+               kind=COUNTER, counts='coverage_downgraded', tags=('discovery', 'coverage')),
+        Metric(name='discovery_handover_dropped', description='Times handover chains were dropped.',
+               kind=COUNTER, counts='handover_dropped', tags=('discovery', 'handover')),
+    )
+    EVERY = (
+        Every(seconds=60, run='publish_coverage', name='coverage'),
+        Every(seconds=300, run='publish_discovery', name='discovery'),
+    )
+    NEEDS = (
+        Need('keystore', 'ks'),
+        Need('store', 'stores.events'),
+        Need('face'),
+        Need('relays'),
+        Need('capacity'),
+        Need('timeout'),
+        Need('persist_cfg'),
+        Need('descriptor'),
+        Need('accounts', 'stores.accounts'),
+        Need('cfg'),
+    )
+    STORES = (
+        st.Store(
+            key='_discovery',
+            description='d -> what was last put on the relays',
+            bound=1024,
+            evict=st.LRU,
+            kind=st.TABLE,
+            keyed_by='d',
+        ),
+        st.Store(
+            key='_coverage',
+            description='shard -> (fingerprint, completeness, range) last published',
+            bound=1024,
+            evict=st.LRU,
+            kind=st.TABLE,
+            keyed_by='shard',
+        ),
+        st.Store(
+            key='_claims',
+            description='shard -> the signed kind 30803 last published',
+            bound=1024,
+            evict=st.LRU,
+            kind=st.TABLE,
+            keyed_by='shard',
+        ),
+        st.Store(
+            key='_handed',
+            description='shard -> pubkey of the peer whose handover the claim rests on',
+            bound=1024,
+            evict=st.LRU,
+            kind=st.TABLE,
+            keyed_by='shard',
+        ),
+        st.Store(
+            key='_narrowed',
+            description='shard -> whether it is currently held back under pressure',
+            bound=1024,
+            evict=st.LRU,
+            kind=st.TABLE,
+            keyed_by='shard',
+        ),
+        st.Store(
+            key='_downgraded',
+            description='shard -> the size at which it was last said to be best-effort',
+            bound=1024,
+            evict=st.LRU,
+            kind=st.TABLE,
+            keyed_by='shard',
+        ),
+        st.Store(
+            key='_forward',
+            description='addressable coordinate -> last created_at stamped',
+            bound=1024,
+            evict=st.LRU,
+            kind=st.TABLE,
+            keyed_by='coordinate',
+        ),
+    )
+    COMMANDS = (
+        Command(
+            key='show',
+            name='Discovery',
+            description='what this node has published about itself and about the shards it holds',
+            tags=('discovery', 'status'),
+            permission='discovery/show',
+            run='state',
+            reply='{discovery, coverage, handed, narrowed, downgraded}',
+        ),
+    )
+
+    def __init__(
+        self,
+        keystore: Any,
+        store: Any,
+        face: Any,
+        relays: Sequence[str],
+        capacity: Optional[Any] = None,
+        clock: Optional[Callable[[], int]] = None,
+        timeout: float = 15.0,
+        node: Optional[Any] = None,
+        persist_cfg: Optional[Callable[[], None]] = None,
+        descriptor: Optional[Callable[[], Optional[NostrEvent]]] = None,
+        accounts: Optional[Any] = None,
+        cfg: Optional[MutableMapping[str, Any]] = None,
+        publisher: Optional[Callable[[Sequence[str], Any, float], Any]] = None,
+    ) -> None:
+        super().__init__(node, clock)
+        # How a discovery or coverage event reaches the relays; given so a
+        # suite can record them without a socket.
+        self.publisher: Callable[[Sequence[str], Any, float], Any] = publisher or relay.publish_all
+        # Named from ctx in a node: the descriptor getter (built in start(),
+        # after this), the account store a handover chain is read from, and
+        # the live config dict a closed range is written into before
+        # persist_cfg saves it. A fake node in a suite supplies the same.
+        self.descriptor: Callable[[], Optional[NostrEvent]] = descriptor or (lambda: getattr(node, 'descriptor', None))
+        self.accounts: Optional[Any] = accounts if accounts is not None else getattr(node, 'accounts', None)
+        self._live_cfg: Optional[MutableMapping[str, Any]] = cfg if cfg is not None else getattr(node, 'cfg', None)
+        self.ks: Any = keystore
+        self.store: Any = store
+        self.face: Any = face
+        self.relays: list[str] = list(relays)  # not a store: the configured relays
+        self.capacity: Optional[Any] = capacity
+        # How a changed coverage claim is written back; the node's writer
+        # when assembled, else the legacy reach into node.save_coverage.
+        self.persist_cfg: Callable[[], None] = persist_cfg or (
+            lambda: getattr(node, 'save_coverage', lambda: None)())
+        self.timeout: float = timeout
+        self._discovery: st.Table[str, str]      # d -> what was last put on the relays, so a tick republishes only a change
+        self._coverage: st.Table[str, tuple[str, str, tuple[Optional[str], Optional[str]]]]   # shard -> (fingerprint, completeness, range) last published
+        # shard -> the signed kind 30803 last published, which is what a handover copies its terms from
+        self._claims: st.Table[str, NostrEvent]
+        self._handed: st.Table[str, str]                     # shard -> pubkey of the peer whose handover the claim rests on
+        self._narrowed: st.Table[str, bool]       # shard -> whether it is currently held back under pressure
+        self._downgraded: st.Table[str, int]     # shard -> the size at which it was last said to be best-effort
+        self._forward: st.Table[str, int]        # addressable coordinate -> last created_at stamped
+
+    _tick_runs_every = True
+
+    def tick(self, now: int) -> list[tuple[Any, ...]]:
+        return self.publish_coverage(now) + self.publish_discovery(now)
+
+    # ---- the forward clock ----------------------------------------------------
+    def forward_clock(self, key: str, now: int) -> int:
+        """A timestamp strictly later than the last one used for this key.
+
+        Every addressable event a node republishes under a stable `d` - the
+        grant envelope, the coverage claim, the report - replaces the last one
+        at that coordinate, and NIP-01 breaks a created_at tie on the *lower*
+        id. Two written in the same second therefore leave the relay holding
+        whichever id happens to sort first, which is the older one about half
+        the time. Supersession only runs forwards, so the clock this node
+        stamps them with only runs forwards too.
+        """
+        last = self._forward.get(key)
+        if last is not None and now <= last:
+            now = last + 1
+        self._forward[key] = now
+        return now
+
+    # ---- the node's own face --------------------------------------------------
+    def publish_discovery(self, now: Optional[int] = None) -> list[tuple[Any, ...]]:
+        """The node's face described for NIP-66 readers: one kind 30166 per
+        ws or wss endpoint the descriptor declares. Bridge 1 in the
+        specification. It says what the face is and accepts and measures
+        nothing, so it changes only when the descriptor, the NIP-11 document
+        or the claimed shards do, and is republished only then."""
+        now_val = now if now is not None else self.clock()
+        did: list[tuple[Any, ...]] = []
+        descriptor = self.descriptor()
+        if not self.relays or descriptor is None or self.face is None:
+            return did
+        shards = [c['shard'] for c in self.config('coverage') or [] if isinstance(c, dict) and c.get('shard')]
+        for ev in ref_discovery.discovery(descriptor, self.face.nip11(), shards, now_val):
+            d = [t[1] for t in ev['tags'] if t[0] == 'd'][0]
+            fingerprint = ref_discovery.settled(ev)
+            if self._discovery.get(d) == fingerprint:
+                continue
+            problems = ref_discovery.check_discovery(ev, descriptor)
+            if problems:
+                self.refusals.refuse('discovery', 'contradicts the descriptor', subject=d,
+                                     detail={'problems': problems[:2]}, at=now_val)
+                did.append(('discovery refused', d, '; '.join(problems[:2])))
+                continue
+            at = self.forward_clock('discovery:' + d, now_val)
+            signed = ref_store.make_signed_event(self.ks.node_sk, at, ref_discovery.KIND,
+                                                 ev['tags'], ev['content'])
+            self.publisher(self.relays, signed, self.timeout)
+            self._discovery[d] = fingerprint
+            did.append(('discovery', d, '%d nips' % len([t for t in ev['tags'] if t[0] == 'N'])))
+        return did
+
+    # ---- what this node holds -------------------------------------------------
+    def publish_coverage(self, now: Optional[int] = None) -> list[tuple[Any, ...]]:
+        """Tell the mesh which shards this node holds, as kind 30803.
+
+        Nothing published one of these before, so no peer could discover what
+        any node held: the whole of data discovery, as distinct from node
+        discovery, was missing.
+
+        `asserted` is a falsifiable claim - a peer may sample the shard, find a
+        hole, and file an S3 with the missing event id as evidence - and the
+        specification forbids asserting completeness over a shard held only
+        through mesh replication, because that is how third-party replication
+        launders unverified peer data into an authoritative record. So the
+        operator's `asserted` is a request and not a decision: it is honoured
+        only when every event in the shard arrived here directly, and downgraded
+        to `best-effort` otherwise, with the reason logged. A leaf publishes
+        neither, having nothing to claim.
+
+        The one door through that is a handover: the first-hand holder's signed
+        statement over the set, received on the sync thread that pulled it and
+        kept in the account store. With one held for the shard, and only while
+        what this node holds over the handed range still fingerprints to what
+        was handed, the claim goes out `asserted` over exactly that range with
+        the handover inline. The moment the set moves - a late event in a
+        closed range, a retention pass - the handover is stale, and a claim
+        that carried it would be a false one, so it is dropped and the claim
+        falls back to what this node can stand behind on its own.
+        """
+        now_val = now if now is not None else self.clock()
+        did: list[tuple[Any, ...]] = []
+        if self.config('class') == 'leaf' or not self.relays:
+            return did
+        for shard in self.config('coverage') or []:
+            filt = shard['filter']
+            since, until = shard.get('since', 0), shard.get('until', 2 ** 31)
+            ids = self.store.enumerate_range(filt, since, until, now_val)
+            if self.capacity is not None and self.capacity.narrowing() and self.store.any_replicated(ids):
+                # Under pressure a node stops advertising what it holds only
+                # second-hand. What it holds first-hand it keeps claiming,
+                # because that is the part it can stand behind. The claims
+                # already published lapse at their own expiration.
+                if self._narrowed.get(shard['shard']) is not True:
+                    self._narrowed[shard['shard']] = True
+                    self.say('coverage_narrowed', shard=shard['shard'])
+                    self.refusals.refuse('coverage', 'held back while this node sheds',
+                                         subject=shard['shard'], at=now_val)
+                    # Stopping the republication is not the same as taking the
+                    # claim back. The one already on the relays is what readers
+                    # act on, and it says this node holds the shard for as long
+                    # as it sits there. The rung means to stop being asked for
+                    # what this node can no longer serve, so the claim is
+                    # withdrawn rather than left to stand unrefreshed.
+                    did += self._withdraw_one(shard['shard'], now_val)
+                    did.append(('coverage narrowed', shard['shard'], 'held through the mesh'))
+                continue
+            self._narrowed.pop(shard['shard'], None)
+            wanted = shard.get('completeness', 'best-effort')
+            completeness = wanted
+            handover: Optional[list[HandoverLink]] = None
+            if wanted == 'asserted' and self.store.any_replicated(ids):
+                handover, h_since, h_until, h_ids = self._handed_set(shard, filt, now_val)
+                if handover is not None:
+                    since, until, ids = h_since, h_until, h_ids
+            if handover is None and wanted == 'asserted' and self.store.any_replicated(ids):
+                completeness = 'best-effort'
+                if self._downgraded.get(shard['shard']) != len(ids):
+                    self._downgraded[shard['shard']] = len(ids)
+                    self.say('coverage_downgraded', shard=shard['shard'])
+                    self.refusals.refuse('coverage', 'asserted was downgraded to best-effort',
+                                         subject=shard['shard'], detail={'events': len(ids)}, at=now_val)
+            at = self.forward_clock('coverage:' + shard['shard'], now_val)
+            if handover is not None:
+                claim = coverage.coverage_claim(self.ks.node_pk, shard['shard'], filt, completeness,
+                                                 ids, at, since=since, until=until, handover=handover)
+            else:
+                claim = coverage.coverage_claim(self.ks.node_pk, shard['shard'], filt, completeness,
+                                                 ids, at, since=shard.get('since'), until=shard.get('until'))
+            problems = coverage.check_coverage(claim, self.config('class'))
+            if problems:
+                self.refusals.refuse('coverage', 'the claim is not one this node may make',
+                                     subject=shard['shard'], detail={'problems': problems[:2]}, at=now_val)
+                did.append(('coverage claim refused', shard['shard'], '; '.join(problems[:2])))
+                continue
+            signed = ref_store.make_signed_event(self.ks.node_sk, at, claim['kind'],
+                                                 claim['tags'], claim['content'])
+            fingerprint = [t[1] for t in signed['tags'] if t[0] == 'fingerprint'][0]
+            self._claims[shard['shard']] = signed
+            if handover is not None:
+                self._handed[shard['shard']] = handover[-1]['from']
+            else:
+                self._handed.pop(shard['shard'], None)
+            # The range is part of what changed: close_ranges() bounds a shard
+            # whose set and completeness are exactly as before, and a handover
+            # signs for that closed set - a dedupe on the set alone kept the
+            # closed claim in memory and never sent it.
+            key = (fingerprint, completeness, _range_of(signed))
+            if self._coverage.get(shard['shard']) == key:
+                continue          # nothing about the shard has changed
+            self.publisher(self.relays, signed, self.timeout)
+            self._coverage[shard['shard']] = key
+            did.append(('coverage', shard['shard'], completeness, '%d events' % len(ids))
+                       + (('handed over by ' + handover[-1]['from'][:16],) if handover is not None else ()))
+        return did
+
+    def _handed_set(
+        self,
+        shard: CoverageShardConfig | Mapping[str, Any],
+        filt: Mapping[str, Any],
+        now: int,
+    ) -> tuple[Optional[list[HandoverLink]], Optional[int], Optional[int], list[str]]:
+        """(chain, since, until, ids) for a shard held under a handover, or
+        (None, None, None, []) when there is none or it no longer fits.
+
+        `handover.still_fits` decides; this drops what no longer does and says
+        why, because the operator asked for asserted and is about to get
+        best-effort without having changed anything.
+        """
+        if self.accounts is None:
+            return None, None, None, []
+        chain = self.accounts.handover(shard['shard'])
+        if not chain:
+            return None, None, None, []
+        art = chain[-1]
+        ids = self.store.enumerate_range(filt, art.get('since') or 0, art['until'], now)
+        why = handover.still_fits(chain, filt, ids)
+        if why is None:
+            return chain, art.get('since'), art['until'], ids
+        self.accounts.drop_handover(shard['shard'])
+        self.say('handover_dropped', shard=shard['shard'], from_peer=art['from'][:16], why=why)
+        self.refusals.refuse('coverage', 'handover dropped: ' + why, subject=shard['shard'],
+                             detail={'from': art['from'], 'held': len(ids), 'handed': art['count']}, at=now)
+        return None, None, None, []
+
+    # ---- retiring --------------------------------------------------------------
+    def close_ranges(self, now: Optional[int] = None) -> list[tuple[Any, ...]]:
+        """Give every asserted shard a bounded range that ends now, and publish.
+
+        A handover signs for a closed set, so a shard whose `until` is open or
+        in the future cannot be handed to anybody. That is the right rule while
+        a node is running and the wrong state to retire in: the shards worth
+        passing on are exactly the ones nobody has ever bounded. Closing them
+        is the first step of a retirement and the only one that changes what
+        this node says about itself while it is still serving.
+
+        Written to the config, because the claim is republished from the config
+        on the next tick and a range closed only in memory would reopen.
+        """
+        now_val = now if now is not None else self.clock()
+        did: list[tuple[Any, ...]] = []
+        cov = [dict(c) for c in self.config('coverage') or [] if isinstance(c, dict)]
+        touched = False
+        for shard in cov:
+            if shard.get('completeness') != 'asserted':
+                continue
+            if shard.get('until') is not None and int(shard['until']) <= now_val:
+                continue
+            shard['until'] = now_val
+            touched = True
+            did.append(('range closed', shard['shard'], now_val))
+        if not touched:
+            return did
+        if self._live_cfg is not None:
+            self._live_cfg['coverage'] = cov
+        self.persist_cfg()
+        return did + self.publish_coverage(now_val)
+
+    def _withdraw_one(self, shard: str, now: int, lapses_in: int = 86400) -> list[tuple[Any, ...]]:
+        """Take one published claim back. Never raises: every caller is either
+        shedding or stopping, and neither may be stopped by a relay."""
+        claim = self._claims.get(shard)
+        if claim is None:
+            return []
+        try:
+            out = coverage.withdraw_coverage(claim, self.forward_clock('coverage:' + shard, now), lapses_in)
+            signed = ref_store.make_signed_event(self.ks.node_sk, out['created_at'], out['kind'],
+                                                 out['tags'], out['content'])
+            self.publisher(self.relays, signed, self.timeout)
+            self._coverage.pop(shard, None)
+            self._claims[shard] = signed
+            return [('coverage withdrawn', shard, 'lapses in %ds' % lapses_in)]
+        except Exception as e:
+            return [('coverage withdrawal failed', shard, '%s: %s' % (type(e).__name__, e))]
+
+    def withdraw_coverage(self, now: Optional[int] = None, lapses_in: int = 86400) -> list[tuple[Any, ...]]:
+        """Take back every claim this node published, so none outlives it.
+
+        A kind 30803 that outlives its node is the black hole: readers see a
+        holder, pull, and time out, and every one of them records strain
+        against a node that is simply gone. The claim is addressable, so a
+        republication at the same `d` replaces it; the replacement says
+        best-effort, which promises nothing, and carries an expiration so it
+        lapses too.
+
+        Last of the retirement, after the handovers: a withdrawal before them
+        would take back the very claim a handover copies its terms from.
+        """
+        now_val = now if now is not None else self.clock()
+        did: list[tuple[Any, ...]] = []
+        for shard in sorted(self._claims):
+            did += self._withdraw_one(shard, now_val, lapses_in)
+        return did
+
+    def asserted_claims(self) -> list[NostrEvent]:
+        """Every published claim this node may hand over: asserted, with a
+        range that has closed. What `close_ranges` has just made of them."""
+        now = self.clock()
+        out: list[NostrEvent] = []
+        for _shard, claim in sorted(self._claims.items()):
+            if not coverage.reportable(claim):
+                continue
+            until = [t for t in claim['tags'] if t[0] == 'until']
+            if until and len(until[0]) > 1 and int(until[0][1]) <= now:
+                out.append(claim)
+        return out
+
+    def published_claim(self, shard: str) -> Optional[NostrEvent]:
+        """The signed kind 30803 this node last published for a shard, or None.
+        What a handover copies its terms from: a node hands over what it has
+        said in public and nothing else."""
+        return self._claims.get(shard)
+
+    # ---- being watched --------------------------------------------------------
+    def state(self) -> DiscoveryStateReport:
+        return {
+            'discovery': sorted(self._discovery),
+            'coverage': {s: c for s, (_, c, _r) in self._coverage.items()},
+            'handed': dict(self._handed),
+            'narrowed': sorted(s for s, v in self._narrowed.items() if v),
+            'downgraded': sorted(self._downgraded),
+        }
+
+    def trouble(self) -> list[str]:
+        out: list[str] = []
+        narrowed = sorted(s for s, v in self._narrowed.items() if v)
+        if narrowed:
+            out.append('%d shard(s) are no longer claimed while this node sheds: %s. '
+                       'A peer looking for that data will not find this node'
+                       % (len(narrowed), ', '.join(narrowed)))
+        refused = self.refusals.within(self.TROUBLE_WINDOW, self.clock(),
+                                       why='the claim is not one this node may make')
+        if refused:
+            out.append('%d coverage claim(s) refused: %s'
+                       % (len(refused), ', '.join(sorted({(r.subject or '') for r in refused}))))
+        return out

node/planes/identity/discovery/types.py

@@ -0,0 +1,13 @@
+"""Types and records for the Discovery compartment."""
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class DiscoveryStateReport(TypedDict, total=False):
+    """The report Discovery.state() gives of itself."""
+    discovery: list[str]
+    coverage: dict[str, str]
+    handed: dict[str, str]
+    narrowed: list[str]
+    downgraded: list[str]

node/planes/identity/linked/__init__.py

@@ -0,0 +1 @@
+"""The node's schema.org face: read-only JSON-LD projections over HTTP."""