Source code for fleetmesh_node.planes.peering.strain.compartment

"""What this node has survived, and the reserves it sets.

`fleetmesh_core/strain.py` is the arithmetic and states why this is safe to act on. This is
the part that records and remembers.

Everything here was already being thrown away. A restart, a peer that went quiet
mid-session, a relay that dropped its subscription, a clock that drifted past
tolerance - the node correctly refuses to make any of them a finding about a
peer, and then discards them, so the information goes out with the accusation.

Nothing recorded here crosses the wire and nothing here is a finding. What it
does is thicken what this node holds in hand: how long it keeps accounting a
vanished peer might still need, and how long it goes on trying a door that was
closed. A node that has weathered a thing becomes better prepared for that thing,
which is the only kind of adaptation an attacker gains nothing by provoking.
"""
from __future__ import annotations

from typing import Any, Callable, Optional


from .types import FlagTreeReport, StrainStateReport

import dataclasses
from fleetmesh_core.accounting import strain as ref_strain
from fleetmesh_core.wire.interfaces import StrainDirection
from fleetmesh_node.compartment import stores as st
from fleetmesh_node.channels import Channel, NOTE
from fleetmesh_node.metrics import COUNTER, Metric
from fleetmesh_node.compartment import Command, Compartment, Need
from fleetmesh_node.config.parameter import Parameter, ParamBlock

# `ref_strain.direction` normalises None to '' so a direction is always three
# strings; the ledger keys on the same shape so the ref arithmetic can take
# its dicts unchanged.
DirectionTuple = StrainDirection

# fleetmesh_core/strain.py annotates KINDS as tuple[int, ...] but constants.json lists
# strings; keep a correctly-typed view here so the membership check below is
# checked as str-in-str. Fix belongs in fleetmesh_core/ (not owned here).
_KINDS: frozenset[str] = frozenset(str(k) for k in ref_strain.KINDS)


[docs]@dataclasses.dataclass(frozen=True) class StrainConfig(ParamBlock): key = 'strain' name = 'strain' DERIVED: bool = False PARAMS = ( Parameter(key='max_directions', name='Max Directions', description='Maximum directions tracked in strain ledger', type=int, default=4096, tags=('strain', 'reserves')), ) max_directions: int = 4096
[docs]class StrainLedger(Compartment): """What this node has survived, as a compartment the operator can watch. It reads no config and changes nothing about any peer: what it holds is the node's own reserves. Its trouble is the flag tree - a node whose strain is nearly all one direction is structurally dependent on that peer and will snap when it leaves, and nothing else in the protocol says so. """ name: str = 'strain' config_cls = StrainConfig CHANNELS = ( Channel('strain_recorded', 'Strain event recorded in ledger', level=NOTE, say='strain event {kind} recorded', tags=('strain', 'reserves')), ) METRICS = ( Metric(name='strain_events_recorded', description='Times strain events were recorded.', kind=COUNTER, counts='strain_recorded', tags=('strain', 'reserves')), ) NEEDS = ( Need('accounts', 'stores.accounts'), Need('ledger', 'ledger'), ) COMMANDS = ( Command( key='show', name='Strain', description='what this node has survived, by direction, and the reserves it sets', tags=('strain', 'status'), permission='strain/show', run='state', reply='{kinds, directions, weighted_directions, reserve_multiple, dominant_share, flag_tree}', ), ) STORES = ( st.Store(key='counts', description='strain counts per direction and kind', kind=st.TABLE, shape=dict, bound=4096, keyed_by='direction', evict=st.LRU), st.Store(key='last', description='strain last timestamp per direction and kind', kind=st.TABLE, shape=dict, bound=4096, keyed_by='direction', evict=st.LRU), )
[docs] def __init__( self, accounts: Optional[Any] = None, clock: Optional[Callable[[], int]] = None, tier_of: Optional[Callable[[str], str]] = None, node: Optional[Any] = None, ledger: Optional[Any] = None, ) -> None: super().__init__(node, clock) self.accounts: Optional[Any] = accounts if tier_of is None and ledger is not None: self.tier_of: Callable[[str], str] = lambda pk: getattr(ledger, 'tier', {}).get(pk, 'probation') else: self.tier_of = tier_of or (lambda _pk: 'probation') self.counts: st.Table[DirectionTuple, dict[str, int]] # direction -> kind -> n self.last: st.Table[DirectionTuple, dict[str, int]] # direction -> kind -> when if accounts is not None: for peer, shard, transport, kind, n, at in accounts.strain(): d = ref_strain.direction(peer, shard, transport) self.counts.setdefault(d, {})[kind] = n self.last.setdefault(d, {})[kind] = at
[docs] def record( self, kind: str, peer: Optional[str] = None, shard: Optional[str] = None, transport: Optional[str] = None, at: Optional[int] = None, n: int = 1, ) -> Optional[DirectionTuple]: """One thing survived. Silently ignores a kind the digest does not name, so a caller cannot invent a category that no reserve reads.""" if kind not in _KINDS: return None at_val = at if at is not None else self.clock() d = ref_strain.direction(peer, shard, transport) self.counts.setdefault(d, {})[kind] = self.counts.get(d, {}).get(kind, 0) + n self.last.setdefault(d, {})[kind] = at_val if self.accounts is not None: self.accounts.put_strain(peer, shard, transport, kind, at_val, n) return d
# ---- the direction rule ---------------------------------------------------
[docs] def by_direction(self, kind: Optional[str] = None) -> dict[DirectionTuple, int]: """direction -> how much stress came from it. Magnitude is collected here and deliberately thrown away by `ref_strain.weigh`, which caps each direction: one peer moves this node by at most one direction's worth.""" out: dict[DirectionTuple, int] = {} for d, kinds in self.counts.items(): n = kinds.get(kind, 0) if kind else sum(kinds.values()) if n: out[d] = n return out
[docs] def weight(self, kind: Optional[str] = None) -> float: return ref_strain.weigh(self.by_direction(kind), self.tier_of)
[docs] def multiple(self, kind: Optional[str] = None) -> float: return ref_strain.multiple(self.weight(kind))
[docs] def reserve(self, base: float | int, kind: Optional[str] = None) -> float: return ref_strain.reserve(base, self.by_direction(kind), self.tier_of)
# ---- the compartment contract -------------------------------------------------
[docs] def tick(self, now: int) -> list[tuple[Any, ...]]: return [] # it records what happens to it; it does not act
def _bent(self) -> tuple[Optional[FlagTreeReport], float, float]: """(flag tree or None, dominant share, strain from every OTHER external direction). A flag tree is bent away from the other winds. On a mesh with one shard every partition is filed under that shard's anchor, so a node has seen exactly one external direction and is 100% of it for ever - the anchor included, against itself. That is the only wind there is, not a deformity, and there is nothing to compare the shape against until another direction has been measured as a pattern (flag_tree_min_events, the same bar the dominant one had to clear).""" st = self.state() ft = st.get('flag_tree') if not ft: return None, 0.0, 0.0 ext = ref_strain.external(self.by_direction()) key = tuple(ft.get('direction') or ()) others = sum(float(n) for d, n in ext.items() if tuple(d) != key) return ft, float(st.get('dominant_share', 0)), others def _flag_tree_line(self, ft: FlagTreeReport, share: float) -> str: return ( '%.0f%% of the strain this node has seen is one direction (%s): it is ' 'structurally dependent on it and will snap when it leaves' % (100 * share, ' / '.join(x for x in (ft.get('direction') or []) if x)[:40]) )
[docs] def trouble(self) -> list[str]: ft, share, others = self._bent() if ft is None or others < float(ref_strain.C['flag_tree_min_events']): return [] return [self._flag_tree_line(ft, share)]
[docs] def notes(self) -> list[str]: ft, share, others = self._bent() if ft is None or others >= float(ref_strain.C['flag_tree_min_events']): return [] return [self._flag_tree_line(ft, share) + '. It is also the only direction this node has been stressed from ' '(%d event(s) from anywhere else), so the shape is the mesh, not a fault' % int(others)]
# ---- the operator's view --------------------------------------------------
[docs] def flag_tree(self) -> FlagTreeReport: key, share = ref_strain.flag_tree(self.by_direction()) return {'direction': list(key) if key else None, 'share': round(share, 4)}
[docs] def state(self) -> StrainStateReport: by = self.by_direction() totals: dict[str, int] = {} for kinds in self.counts.values(): for k, n in kinds.items(): totals[k] = totals.get(k, 0) + n key, share = ref_strain.flag_tree(by) st: StrainStateReport = { 'kinds': totals, 'directions': len(by), 'weighted_directions': round(self.weight(), 4), 'reserve_multiple': round(self.multiple(), 3), 'dominant_share': round(share, 4), } if key is not None: st['flag_tree'] = { 'direction': list(key), 'note': ( 'nearly all the strain this node has seen comes from one direction, ' 'so it is structurally dependent on it and will snap when it leaves. ' 'This is not a finding about that peer, which has done nothing but be ' 'the only one there' ), } return st