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