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