fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/peering/strain/compartment.py

@@ -0,0 +1,204 @@
+"""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 node.compartment import stores as st
+from node.channels import Channel, NOTE
+from node.metrics import COUNTER, Metric
+from node.compartment import Command, Compartment, Need
+from 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)
+
+
+@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
+
+
+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),
+    )
+
+    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
+
+    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 ---------------------------------------------------
+    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
+
+    def weight(self, kind: Optional[str] = None) -> float:
+        return ref_strain.weigh(self.by_direction(kind), self.tier_of)
+
+    def multiple(self, kind: Optional[str] = None) -> float:
+        return ref_strain.multiple(self.weight(kind))
+
+    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 -------------------------------------------------
+    def tick(self, now: int) -> list[tuple[Any, ...]]:
+        return []          # it records what happens to it; it does not act
+
+    def trouble(self) -> list[str]:
+        ft = self.state().get('flag_tree')
+        if not ft:
+            return []
+        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 * self.state().get('dominant_share', 0),
+                ' / '.join(x for x in (ft.get('direction') or []) if x)[:40],
+            )
+        ]
+
+    # ---- the operator's view --------------------------------------------------
+    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)}
+
+    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

node/planes/peering/strain/types.py

@@ -0,0 +1,21 @@
+"""Types and records for the Strain compartment."""
+from __future__ import annotations
+
+from typing import Optional, TypedDict
+
+
+class FlagTreeReport(TypedDict, total=False):
+    """Dominant strain direction and its share."""
+    direction: Optional[list[str]]
+    share: float
+    note: Optional[str]
+
+
+class StrainStateReport(TypedDict, total=False):
+    """The report Strain.state() gives of itself."""
+    kinds: dict[str, int]
+    directions: int
+    weighted_directions: float
+    reserve_multiple: float
+    dominant_share: float
+    flag_tree: Optional[FlagTreeReport]

node/planes/peering/trust/__init__.py

@@ -0,0 +1,9 @@
+"""The operator's own decisions about peers, carried out once each.
+
+One-module compartment: everything is in compartment.py.
+"""
+from .compartment import Trust
+from .types import TrustDecisionDetail, TrustStandingRow, TrustStateReport
+
+__all__ = ['Trust', 'TrustDecisionDetail', 'TrustStandingRow', 'TrustStateReport']
+

node/planes/peering/trust/compartment.py

@@ -0,0 +1,239 @@
+"""The operator's own decisions about peers, carried out once each.
+
+A tier is only ever raised by a person. The ladder earns standing with observed
+time; the specification says an operator MAY seed a tier for a node it knows out
+of band, recorded as a signed event and reversible. `meshnode trust` writes that
+decision to the config file and this compartment is what acts on it.
+
+It ran inside the node's tick before, which meant a seed that could not be
+applied - no peering yet, or a regrant that came back empty - was skipped in
+silence. An operator who had written a decision and watched nothing happen had
+no way to ask why. Every skip is a refusal here.
+"""
+from __future__ import annotations
+
+import dataclasses
+from typing import Any, Callable, Mapping, Optional
+
+from node.storage import grants as grants_mod
+from node.compartment import stores as st
+from node.channels import Channel, NOTE, TROUBLE
+from node.metrics import COUNTER, Metric
+from node.compartment import Command, Compartment, Need
+from node.config.parameter import Parameter, ParamBlock
+
+
+from .types import (
+    TrustStandingRow,
+    TrustStateReport,
+)
+
+
+def decision(entry: Any) -> tuple[str, int]:
+    """A trust entry is {'tier': t, 'at': unix} - or, from before decisions
+    were dated, the bare tier, which counts as decided at time zero."""
+    if isinstance(entry, dict):
+        return entry.get('tier', 'probation'), int(entry.get('at') or 0)
+    return entry, 0
+
+
+def tiers(trust: Optional[Mapping[str, Any]]) -> dict[str, str]:
+    """The policy's view: peer -> tier."""
+    return {pk: decision(e)[0] for pk, e in (trust or {}).items()}
+
+
+@dataclasses.dataclass(frozen=True)
+class TrustConfig(ParamBlock):
+    key = 'trust'
+    name = 'trust'
+    DERIVED: bool = False
+    PARAMS = (
+        Parameter(key='max_decisions', name='Max Decisions', description='Maximum trust decisions remembered', type=int, default=4096, live=True, tags=('trust', 'policy')),
+    )
+    max_decisions: int = 4096
+
+
+class Trust(Compartment):
+
+    name: str = 'trust'
+    reads: tuple[str, ...] = ('trust',)
+    live: tuple[str, ...] = ('trust',)
+    config_cls = TrustConfig
+    CHANNELS = (
+        Channel('trust_applied', 'Trust decision applied for peer', level=NOTE, say='trust decision applied for peer {peer}', tags=('trust', 'policy')),
+        Channel('trust_refused', 'Trust decision refused for peer', level=TROUBLE, say='trust decision refused for peer {peer}: {reason}', tags=('trust', 'policy')),
+    )
+    METRICS = (
+        Metric(name='trust_decisions_applied', description='Times trust decisions were applied.', kind=COUNTER, counts='trust_applied', tags=('trust', 'policy')),
+        Metric(name='trust_decisions_refused', description='Times trust decisions were refused.', kind=COUNTER, counts='trust_refused', tags=('trust', 'policy')),
+    )
+    NEEDS = (
+        Need('grant_store', 'stores.grants'),
+        Need('policy', 'policy'),
+        Need('regrant', 'regrant'),
+    )
+    COMMANDS = (
+        Command(
+            key='show',
+            name='Trust',
+            description='the decisions this operator has made, and which of them are still in '
+                        'force: carried out is not the same as true, and the ladder can move a '
+                        'seeded peer',
+            tags=('trust', 'status'),
+            permission='trust/show',
+            run='state',
+            reply='{decided, in_force, pending, overridden, waiting}',
+        ),
+    )
+    STORES = (
+        st.Store(key='_said', description='refused decisions said once, per peer',
+                 kind=st.TABLE, shape=tuple, bound=4096, keyed_by='peer', evict=st.LRU),
+    )
+
+    def __init__(
+        self,
+        grant_store: grants_mod.GrantStore,
+        policy: Any,
+        regrant: Callable[[str, str, int], Any],
+        clock: Optional[Callable[[], int]] = None,
+        node: Optional[Any] = None,
+    ) -> None:
+        super().__init__(node, clock)
+        self.grants: grants_mod.GrantStore = grant_store
+        self.policy: Any = policy
+        self.regrant: Callable[[str, str, int], Any] = regrant
+        self._said: st.Table[str, tuple[tuple[str, int], str]]     # peer -> the decision already refused, so a wait is said once
+
+    def tick(self, now: int) -> list[tuple[Any, ...]]:
+        """Carry out each dated decision in the config once.
+
+        A decision is compared with the record of decisions applied, kept
+        beside the grants, and not with the grant's tier: comparing tiers made
+        the seed re-issue `trusted` on the tick after every demotion the ladder
+        earned, so the ladder never held and every re-issue was one more
+        amend. A decision written while the node was down is still found on
+        the first tick back, because the record is on disk too. Applying a
+        seed also drops any grant the ladder had waiting for the boundary: the
+        operator's word is the later one.
+        """
+        did: list[tuple[Any, ...]] = []
+        trust = self.config('trust') or {}
+        self.policy.tiers = tiers(trust)
+        for peer_pk, entry in trust.items():
+            tier, at = decision(entry)
+            if self.grants.seed_applied(peer_pk) == (tier, at):
+                continue
+            row = self.grants.get(peer_pk, grants_mod.ISSUED)
+            if row is None or row['status'] != 'live':
+                # No peering yet: the policy seeds the next one. Recorded once
+                # per decision and not once a tick - a refusal repeated every
+                # thirty seconds rolls the buffer that holds the real ones, and
+                # makes trouble() shout about a wait that is not a fault.
+                self._say(peer_pk, (tier, at), 'no live peering to amend', now)
+                continue
+            if row['payload'].get('tier') == tier and self.grants.pending(peer_pk) is None:
+                self.grants.put_seed(peer_pk, tier, at)      # already so; nothing to re-issue
+                continue
+            if self.regrant(peer_pk, tier, now) is not None:
+                self.grants.put_seed(peer_pk, tier, at)
+                self._said.pop(peer_pk, None)
+                did.append(('granted', peer_pk, tier))
+            else:
+                self._say(peer_pk, (tier, at), 'the grant could not be re-issued', now)
+        return did
+
+    def _say(self, peer_pk: str, decided: tuple[str, int], why: str, now: int) -> None:
+        if self._said.get(peer_pk) == (decided, why):
+            return
+        self._said[peer_pk] = (decided, why)
+        self.refusals.refuse('seed', why, subject=peer_pk,
+                             detail={'tier': decided[0], 'at': decided[1]}, at=now)
+
+    def standing(self) -> list[TrustStandingRow]:
+        """Each decision, and what has become of it.
+
+        Three states, not two. `applied` used to mean "this dated decision was
+        carried out at some point", and an operator read it as "the tier I
+        chose is the tier in force". Those diverge the moment the ladder
+        demotes a seeded peer: the seed is recorded as applied, this compartment
+        correctly declines to re-issue it - re-issuing on every demotion is what
+        made the ladder never hold, and the dated record is the fix for that -
+        and the operator's decision quietly stops being true.
+
+        Seen on the mesh. A node seeded `trusted` was demoted to probation in a
+        run of S1 windows, and twelve hours later `trust` still said
+        `applied: 1, waiting: []` while every window ran under a probation
+        ceiling the operator had never chosen. Nothing was wrong with the
+        mechanism. The report was answering a different question from the one
+        being asked of it.
+
+            waiting     decided, not carried out yet
+            pending     carried out, and published at the next window boundary
+            in force    carried out, and the grant says so
+            overridden  carried out, and the ladder has since moved it
+
+        Only the last needs a person, which is why only the last is trouble.
+        `pending` exists because a decision no longer lands the moment it is
+        made: publishing a grant inside a running window breaks the subject's
+        receipt chain for the rest of it, so every decision waits for the
+        boundary. Without this state, the hour between deciding and landing
+        would read as overridden and shout for a person who need do nothing.
+        """
+        out: list[TrustStandingRow] = []
+        for pk, entry in (self.config('trust') or {}).items():
+            tier, at = decision(entry)
+            row = self.grants.get(pk, grants_mod.ISSUED)
+            held = row['payload'].get('tier') if row else None
+            pend = self.grants.pending(pk)
+            if self.grants.seed_applied(pk) != (tier, at):
+                state = 'waiting'
+            elif held == tier:
+                state = 'in force'
+            elif pend is not None and (pend.get('payload') or {}).get('tier') == tier:
+                state = 'pending'
+            else:
+                state = 'overridden'
+            out.append({'peer': pk, 'tier': tier, 'at': at, 'held': held, 'state': state})
+        return out
+
+    def state(self) -> TrustStateReport:
+        rows = self.standing()
+        return {
+            'decided': {
+                r['peer'][:16]: {
+                    'tier': r['tier'],
+                    'at': r['at'],
+                    'held': r['held'],
+                    'state': r['state'],
+                }
+                for r in rows
+            },
+            'in_force': sum(1 for r in rows if r['state'] == 'in force'),
+            'pending': sorted(r['peer'][:16] for r in rows if r['state'] == 'pending'),
+            'overridden': sorted(r['peer'][:16] for r in rows if r['state'] == 'overridden'),
+            'waiting': sorted(r['peer'][:16] for r in rows if r['state'] == 'waiting'),
+        }
+
+    def trouble(self) -> list[str]:
+        """A decision waiting on a peering that does not exist yet is not
+        trouble - it is what a seed written before the peering looks like, and
+        the policy will apply it to the next handshake. A decision that reached
+        a live peering and could not be written is. So is one the ladder has
+        since overridden, because that one looks applied and is not in force,
+        and only a person can decide which of the two answers should stand.
+        """
+        out: list[str] = []
+        stuck = sorted({(pk or '')[:16] for pk, (_, why) in self._said.items()
+                        if why == 'the grant could not be re-issued'})
+        if stuck:
+            out.append('%d trust decision(s) reached a live peering and could not be written: %s. '
+                       'The tier the operator decided on is not the tier in force'
+                       % (len(stuck), ', '.join(stuck)))
+        gone = [r for r in self.standing() if r['state'] == 'overridden']
+        if gone:
+            out.append('%d trust decision(s) the ladder has overridden: %s. '
+                       'Each was carried out and is no longer in force; re-deciding means '
+                       'writing the tier again with a later date'
+                       % (len(gone), ', '.join('%s decided %s, holds %s'
+                                               % (r['peer'][:16], r['tier'], r['held']) for r in gone)))
+        return out

node/planes/peering/trust/types.py

@@ -0,0 +1,30 @@
+"""Types and records for the Trust compartment."""
+from __future__ import annotations
+
+from typing import Optional, TypedDict
+
+
+class TrustStandingRow(TypedDict, total=False):
+    """One standing row from trust decisions."""
+    peer: str
+    tier: str
+    at: int
+    held: Optional[str]
+    state: str
+
+
+class TrustDecisionDetail(TypedDict, total=False):
+    """Decision detail for an evaluated peer."""
+    tier: str
+    at: int
+    held: Optional[str]
+    state: str
+
+
+class TrustStateReport(TypedDict, total=False):
+    """The report Trust.state() gives of itself."""
+    decided: dict[str, TrustDecisionDetail]
+    in_force: int
+    pending: list[str]
+    overridden: list[str]
+    waiting: list[str]

node/planes/services/__init__.py

@@ -0,0 +1,33 @@
+"""Services plane: applications, compute, settlement, paid fetch, sidecars, and data vending.
+
+The 8 compartments of the services plane:
+- gossip: group-topic epidemic fanout over the transport ladder
+- compute: node-side lifecycle, offer publication and job handling
+- compute_wire: routes compute/1.0 and 1.1 envelopes to ComputeSession
+- settle: multi-rail settlement (Lightning hold invoices & Cashu Nutzap)
+- paidfetch: pricing and payment gating for Blossom blob fetches
+- sidecars: external service bridge and health monitoring
+- dvm: NIP-90 Data Vending Machine compute gateway
+- nsite: static site hosting and Blossom mirroring
+"""
+from .gossip import GossipMesh
+from .compute import Compute
+from .compute_wire import ComputeWire
+from .settle import Settlement
+from .paidfetch import PaidFetch
+from .sidecars import Sidecars
+from .dvm import DVMGateway
+from .nsite import NsiteGateway
+from .video import VideoTransitCompartment
+
+__all__ = [
+    'GossipMesh',
+    'Compute',
+    'ComputeWire',
+    'Settlement',
+    'PaidFetch',
+    'Sidecars',
+    'DVMGateway',
+    'NsiteGateway',
+    'VideoTransitCompartment',
+]