Source code for fleetmesh_node.planes.peering.reporter.core

"""The Reporter subsystem itself: construction and restore, what survives a
restart, and the Compartment contract. Separate from the mixins because this is
where the state they all share is created; the mixins are the concerns that
act on it.
"""
from __future__ import annotations

import dataclasses
import threading
from typing import Any, Callable, Mapping, Optional, Sequence

from fleetmesh_node.config.parameter import Parameter, ParamBlock
from fleetmesh_node.channels import Channel, NOTE, TROUBLE, bus as eventbus_mod
from fleetmesh_node.metrics import COUNTER, Metric
from fleetmesh_core.accounting import standing  # noqa: E402
from fleetmesh_core.peering import complaint  # noqa: E402
from fleetmesh_core.wire.interfaces import ComplaintNoticeBody, ComplaintRemedyBody, NostrEvent  # noqa: E402
from fleetmesh_node.storage import grants as grants_mod  # noqa: E402
from fleetmesh_node.compartment import stores as st  # noqa: E402
from fleetmesh_node.compartment import Command, Handler, Need, Outbound, WireProtocol  # noqa: E402
from .constants import FINDING_WINDOWS, KEEP_LOG, KEEP_SIGNED, KEEP_THREADS, KEEP_UNPUBLISHABLE, PUBLISH_TRIES, REPORT_TTL
from .finding import Finding
from .findings import FindingsMixin
from .publish import PublishMixin
from .reading import ReadingMixin
from .types import ReporterStateReport

[docs]@dataclasses.dataclass(frozen=True) class ReporterConfig(ParamBlock): key = 'reporter' name = 'reporter' DERIVED: bool = False PARAMS = ( Parameter( key='report_ttl', name='Report TTL', description='Time-to-live in seconds for signed reports', type=int, default=REPORT_TTL, minimum=86400, tags=('reporter', 'retention'), ), Parameter( key='finding_windows', name='Finding Windows Horizon', description='Window horizon for substantiated findings', type=int, default=FINDING_WINDOWS, minimum=1, tags=('reporter', 'history'), ), Parameter( key='publish_tries', name='Publish Tries', description='Maximum publish attempts before finding marked unpublishable', type=int, default=PUBLISH_TRIES, minimum=1, tags=('reporter', 'publish'), ), ) report_ttl: int = REPORT_TTL finding_windows: int = FINDING_WINDOWS publish_tries: int = PUBLISH_TRIES
[docs]class Reporter(FindingsMixin, PublishMixin, ReadingMixin, WireProtocol): """Findings on their way to a report, as a compartment. Its refusals are complaint and standing messages without the shape of their type, which were kept in a list nothing rendered. Its trouble is the one an operator most needs and would otherwise never see: a finding this node holds and cannot publish, because the subject signed nothing that window and active silence is unreportable by design. """ name: str = 'reporter' piuris: tuple[str, ...] = (complaint.PIURI, standing.PIURI) reads: tuple[str, ...] = ('projection',) config_cls = ReporterConfig CHANNELS = ( Channel('report_published', 'A signed report was published to relays', level=NOTE, say='published report {report_id} on peer {peer}', tags=('reporter', 'publish')), Channel('report_withdrawn', 'A finding or report was withdrawn by operator', level=NOTE, say='withdrew report on peer {peer} window {window}', tags=('reporter', 'withdraw')), Channel('finding_unpublishable', 'An adverse finding could not be published to relays', level=TROUBLE, say='finding on peer {peer} window {window} unpublishable: {reason}', tags=('reporter', 'trouble')), ) METRICS = ( Metric(name='reporter_reports_published', description='Reports published.', kind=COUNTER, counts='report_published', tags=('reporter', 'publish')), Metric(name='reporter_reports_withdrawn', description='Reports withdrawn.', kind=COUNTER, counts='report_withdrawn', tags=('reporter', 'withdraw')), Metric(name='reporter_findings_unpublishable', description='Findings unpublishable.', kind=COUNTER, counts='finding_unpublishable', tags=('reporter', 'trouble')), ) OUTBOUND = ( Outbound('notice', reply='remedy', doc='notify peer of adverse finding'), Outbound('remedy', doc='submit remedy in response to complaint notice'), Outbound('withdraw', doc='withdraw complaint finding'), Outbound('ask', reply=('tell', 'decline'), doc='query peer standing'), Outbound('tell', doc='answer standing query with peer streak'), Outbound('decline', doc='decline standing query'), ) HANDLERS = ( Handler('notice', run='handle_notice', doc='answer complaint notice'), Handler('remedy', run='handle_remedy', doc='receive complaint remedy'), Handler('withdraw', run='handle_withdraw', doc='receive complaint withdrawal'), Handler('ask', run='handle_ask', doc='answer standing ask from ledger'), Handler('*', run='handle_unknown', doc='ignore unknown complaint or standing kind by name'), ) COMMANDS = ( Command( key='show', name='Reporter Status', description='findings held, reports published, and what cannot be published at all', tags=('reporter', 'status'), permission='reporter/show', run='state', reply='{pending, published, withdrawn, unpublishable, noticed, malformed}', ), Command( key='withdraw', name='Withdraw Finding', description="withdraw a finding this node made about one window, published or not; the operator's call", tags=('reporter', 'withdraw'), parameters=( Parameter(key='peer', name='peer', description='peer pubkey or did', type=str, default='', required=True), Parameter(key='window', name='window', description='window number', type=int, default=0, required=True), Parameter(key='why', name='why', description='reason for withdrawal', type=str, default=None, required=False), ), permission='reporter/withdraw', run='withdraw_cmd', reply='{peer, window, was_published, report, why}', ), ) # What it keeps. The three lists of signed events and the log grew by one # per report, score, label or complaint message for the life of the # process, and `remedies_in` - written by any peer that sends a remedy - # was trimmed only when a finding expired. `published` is still counted # whole in `state`, from the ring's inserts. `pending` is not here: it is # the queue `accounts` keeps on disk, for a durable store to declare. STORES = ( st.Store(key='published', description='kind 30802 reports this node signed, newest last', kind=st.RING, shape=dict, bound=KEEP_SIGNED), st.Store(key='projected', description='kind 30385 relay scores this node signed, newest last', kind=st.RING, shape=dict, bound=KEEP_SIGNED), st.Store(key='labeled', description='kind 1985 labels this node signed, newest last', kind=st.RING, shape=dict, bound=KEEP_SIGNED), st.Store(key='unpublishable', description='findings it may not publish, as (peer, window, severity, reasons)', kind=st.RING, shape=tuple, bound=KEEP_UNPUBLISHABLE), st.Store(key='notices_in', description='complaint notices received, where this node is the subject', kind=st.TABLE, shape=dict, bound=KEEP_THREADS, keyed_by='thid'), st.Store(key='remedies_in', description='remedies received, where this node is the issuer', kind=st.TABLE, shape=dict, bound=KEEP_THREADS, keyed_by='thid'), st.Store(key='log', description='withdrawals against this node and tiers it restored, newest last', kind=st.RING, shape=tuple, bound=KEEP_LOG), ) published: st.Ring[NostrEvent] projected: st.Ring[NostrEvent] labeled: st.Ring[NostrEvent] unpublishable: st.Ring[tuple[str, int, str, list[str]]] notices_in: st.Table[str, ComplaintNoticeBody] remedies_in: st.Table[str, ComplaintRemedyBody] log: st.Ring[tuple[Any, ...]] NEEDS = ( Need('keystore', 'ks'), Need('transport'), Need('grant_store', 'stores.grants'), Need('relay_urls', 'relays'), Need('ledger'), Need('project', 'cfg', field='projection'), Need('timeout'), Need('accounts', 'stores.accounts'), Need('regrant'), Need('events'), Need('discovery', late=True), Need('budget', late=True), )
[docs] def start(self) -> None: if self.events is not None: events = self.events self.on_report_read.append(lambda *a: events.emit(eventbus_mod.TOPIC_REPORT_ADMITTED, *a))
[docs] def __init__( self, keystore: Any, transport: Any, grant_store: grants_mod.GrantStore, relay_urls: Sequence[str], ledger: Optional[standing.Ledger] = None, clock: Optional[Callable[[], int]] = None, timeout: float = 15.0, node: Optional[Any] = None, project: bool = True, accounts: Optional[Any] = None, regrant: Optional[Callable[[str, str, int], Any]] = None, events: Optional[Any] = None, discovery: Optional[Any] = None, budget: Optional[Any] = None, ) -> None: super().__init__(node, clock) # The node call that re-issues a grant when a tier is restored; # suites that pass a fake node and nothing else get it off that. self.regrant: Optional[Callable[[str, str, int], Any]] = regrant if regrant is not None else getattr(node, 'regrant', None) self.ks: Any = keystore self.accounts: Optional[Any] = accounts # where pending findings survive a restart; None keeps them in memory self.project: bool = True if project is None else bool(project) # publish the kind 30385 relay score beside each report self.projected: st.Ring[NostrEvent] # the kind 30385 events this node put on the relays self.labeled: st.Ring[NostrEvent] # the kind 1985 NIP-32 labels this node put on the relays self.transport: Any = transport self.grants: grants_mod.GrantStore = grant_store self.relays: list[str] = list(relay_urls) # not a store: the configured relays self.ledger: standing.Ledger = ledger if ledger is not None else standing.Ledger() self.events: Optional[Any] = events self.discovery: Optional[Any] = discovery self.budget: Optional[Any] = budget self._forward_clock: Optional[Callable[[str, int], int]] = None # After the ledger exists and not before it. This read the store into # `self.ledger` four lines above the line that creates it, so a node # started fresh was fine and a node restarted after it had read one # report of anyone's died on the way up with AttributeError - a crash # loop that only ever reached the nodes doing the most work. Two of a # four-node mesh went down this way at once. if accounts is not None: for reporter, rid, bad in accounts.reports_seen(): self.ledger.record_report(reporter, rid, bad) self.timeout: float = timeout self._lock: threading.RLock = threading.RLock() self.pending: list[Finding] = [] # not a store: findings on their way to a report - the queue accounts keeps on disk, for persist=DURABLE self.published: st.Ring[NostrEvent] # kind 30802 events this node put on the relays self.unpublishable: st.Ring[tuple[str, int, str, list[str]]] # findings it may not publish: no evidence a reader can check self.notices_in: st.Table[str, ComplaintNoticeBody] # thid -> notice body received (we are the subject) # Refusals go through the compartment channel. `rejected` stays as a # view in the shape two suites and the health block already read. self.remedies_in: st.Table[str, ComplaintRemedyBody] # thid -> remedy body received (we are the issuer) self.log: st.Ring[tuple[Any, ...]] self.on_report_read: list[Callable[[str, str, str, bool, bool], Any]] = [] # (reporter, target, id, admissible, contradicted) if accounts is not None: self.pending = [Finding.from_dict(b) for b in accounts.findings()] # not a store: loaded from accounts, for persist=DURABLE
@property def forward_clock(self) -> Optional[Callable[[str, int], int]]: if self._forward_clock is not None: return self._forward_clock if getattr(self, 'discovery', None) is not None: return getattr(self.discovery, 'forward_clock', None) return None @forward_clock.setter def forward_clock(self, fn: Optional[Callable[[str, int], int]]) -> None: self._forward_clock = fn # ---- what survives a restart ------------------------------------------------- def _persist(self, p: Finding) -> None: """Write a pending finding down. Called at every change of its state: opened, noticed, remedied, published, unpublishable, withdrawn. Four nodes on three machines showed why. Two London nodes priced two peers S2 at a window close, sent the notices, and were restarted eight minutes later for an unrelated fix. The findings, their evidence and the notice threads were memory only. The window passed and the reports the notices had promised never came, and nothing said so. """ if self.accounts is None: return self.accounts.put_finding(p.fid, p.peer, p.epoch, p.to_dict()) # ---- the compartment contract ------------------------------------------------- @property def rejected(self) -> list[tuple[Optional[str], str, str]]: return [(r.subject, r.kind, r.why) for r in self.refusals.last(200)]
[docs] def state(self) -> ReporterStateReport: held = [p for p in self.pending if not p.done] return { 'pending': len(held), 'published': self.published.inserts, 'withdrawn': sum(1 for p in self.pending if p.withdrawn), 'noticed': sum(1 for p in held if p.notice_at is not None), 'unpublishable': len(self.unpublishable), 'malformed': len(self.rejected), }
[docs] def trouble(self) -> list[str]: stuck = self.unpublishable if not stuck: return [] # The operator's own view of a rule the specification states and nothing # else surfaces: a window of active silence cannot produce a kind 30802, # because the subject signed nothing that window and no reader could # check either half of the claim. The remedy is local and complete. return [ '%d finding(s) can never be published - the subject signed nothing those windows. ' 'The grant is cut locally and standing/1.0 still carries the streak' % len(stuck) ]
[docs] def withdraw_cmd(self, args: Mapping[str, Any]) -> Any: return self.withdraw(str(args['peer']), int(args['window']), args.get('why'))