"""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 fleetmesh_node.compartment import stores as st
from fleetmesh_node.channels import Channel, NOTE, TROUBLE
from fleetmesh_node.metrics import COUNTER, Metric
from fleetmesh_node.protocols.nostr import client as relay
from fleetmesh_node.planes.store.sync import rules as handover
from fleetmesh_node.planes.store.sync.rules import CoverageShardConfig
from fleetmesh_node.interfaces import NostrEvent
from fleetmesh_node.compartment import Command, Compartment, Every, Need
from fleetmesh_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')
[docs]@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
[docs]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('public_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}',
),
)
[docs] 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,
public_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))
# What this node may say to the public relays, or None when it is fully
# private (plan D2): no NIP-66 discovery and no coverage claim then. A
# suite that hands in only a descriptor gets that as the public copy.
self.public_descriptor: Callable[[], Optional[NostrEvent]] = public_descriptor or self.descriptor
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
[docs] def tick(self, now: int) -> list[tuple[Any, ...]]:
return self.publish_coverage(now) + self.publish_discovery(now)
# ---- the forward clock ----------------------------------------------------
[docs] 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 --------------------------------------------------
[docs] 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.public_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 -------------------------------------------------
[docs] 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 or self.public_descriptor() is None:
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 --------------------------------------------------------------
[docs] 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))]
[docs] 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
[docs] 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
[docs] 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 --------------------------------------------------------
[docs] 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),
}
[docs] 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