fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/peering/peering/handshake.py

@@ -0,0 +1,198 @@
+"""The handshake over the wire: the proposer (`propose`), the acceptor
+(`handle`, one inbound peering/1.0 message) and the loop that serves them.
+What each message *means* is fleetmesh_core/peering.py's; this is only the carrying."""
+from __future__ import annotations
+
+import queue
+import threading
+import time
+from typing import Any, Mapping, Optional
+
+from fleetmesh_core.peering import peering
+from fleetmesh_core.storage import replication
+from fleetmesh_core.wire.wire_types import PeeringAcceptBody
+from fleetmesh_core.identity.did import did_nostr
+from node.storage import grants as grants_mod
+from .envelope import PeeringError
+from .shape import PeeringShape
+
+
+from .types import PeeringResultDetail
+
+
+class HandshakeMixin:
+    # ---- proposer ----------------------------------------------------------
+    def propose(
+        self: PeeringShape,
+        peer_pk: str,
+        want: Any,
+        offer: Optional[list[Any]] = None,
+        budget_self: Optional[Mapping[str, Any]] = None,
+        timeout: float = 30.0,
+    ) -> tuple[str, PeeringResultDetail | Mapping[str, Any]]:
+        """Run the whole handshake against one peer. Returns ('peered', detail) or ('declined', body)."""
+        budget_self = budget_self or {'events_in': 600, 'bytes_in': 8388608,
+                                      'window': peering.CONSTANTS['grant']['window_seconds_default']}
+        want_list = want if isinstance(want, list) else [want]
+        proposal = self.host.propose(did_nostr(peer_pk), want_list, offer or [], budget_self,
+                                     pow_event=self.descriptor['id'])
+        reply = self.wire_client.request(peer_pk, proposal, timeout=timeout)
+        if reply is None:
+            raise PeeringError('no answer from %s within %.0fs' % (peer_pk[:16], timeout))
+        msg = reply.message
+        if msg['type'].endswith('/decline'):
+            self.log.append(('declined by', peer_pk, msg['body']))
+            return 'declined', msg['body']
+        if not msg['type'].endswith('/offer'):
+            raise PeeringError('expected an offer, got %s' % msg['type'])
+        held = self.grants.get(peer_pk, grants_mod.ISSUED)
+        if held is not None and held['status'] == 'live':
+            # Already granting this peer: proposing again is a check that the
+            # peering stands, not a reason to reissue at the opening tier and
+            # throw away what the peer's clean windows earned.
+            acc_body: PeeringAcceptBody = {'grant_envelope': held['envelope_id'],
+                                        'selected_transport': msg['body']['transports'][0]}
+            # The row from get() never carried the event - it lives in the
+            # history table - so this used to read a key that was never there
+            # and the re-accept always went out without the envelope.
+            held_event = self.grants.envelope_event(peer_pk, grants_mod.ISSUED, held['envelope_id'])
+            if held_event:
+                acc_body['envelope_event'] = held_event
+            accept = self.host._msg('accept', acc_body,
+                                    did_nostr(peer_pk), thid=proposal['id'])
+            published: dict[str, dict[str, tuple[bool, str]]] = {}
+        else:
+            accept = dict(self.host.accept(msg, did_nostr(peer_pk), want_list, self.clock()))
+            published = self._flush_envelopes()
+            accept_body = dict(accept.get('body', {}))
+            if self.host.envelopes.get(peer_pk):
+                accept_body['envelope_event'] = self.host.envelopes[peer_pk]
+            accept['body'] = accept_body
+            mine = self.host.envelopes.get(peer_pk)
+            self.grants.put(peer_pk, grants_mod.ISSUED, self.host.issued[peer_pk], accept['body']['grant_envelope'],
+                            self.clock(), event=mine, env_created_at=mine['created_at'] if mine else None)
+        self.wire_client.send(peer_pk, accept)
+        received = self._take_received(msg['body']['grant_envelope'], peer_pk, msg['body'].get('envelope_event'))
+        issued = self.host.issued.get(peer_pk) or (held['payload'] if held else None)
+        if held is None or held['status'] != 'live':
+            for cb in self.on_grant_issued:
+                cb(peer_pk, 'accept', accept['body']['grant_envelope'], (issued or {}).get('tier'))
+        for peered in self.on_peered:
+            peered(peer_pk, 'proposer', accept['body']['selected_transport'])
+        return 'peered', {'issued': issued, 'received': received,
+                          'transport': accept['body']['selected_transport'], 'published': published}
+
+    # ---- acceptor ----------------------------------------------------------
+    def handle_propose(self: PeeringShape, inbound: Any, sender: str) -> tuple[Any, ...]:
+        msg = getattr(inbound, 'message', inbound)
+        body = msg.get('body')
+        if not isinstance(body, dict):
+            return ('ignored', sender, 'malformed body')
+        held = self.grants.get(sender, grants_mod.ISSUED)
+        if held is not None and held['status'] == 'live':
+            theirs = {tr: i for i, tr in enumerate(body.get('transports', []))}
+            ladder = replication.negotiate(self.host.policy.transports, theirs) or [next(iter(self.host.policy.transports))]
+            self.host.threads[sender] = msg['id']
+            reply = self.host._msg('offer', {'tier': held['payload']['tier'], 'limits': held['payload']['limits'],
+                                             'transports': ladder, 'grant_envelope': held['envelope_id']},
+                                   msg['from'], thid=msg['id'])
+            self.wire_client.send(sender, reply)
+            return ('re-offered', sender, held['envelope_id'])
+        if self.capacity is not None and self.capacity.refusing():
+            reply = self.host._msg('decline',
+                                   {'code': peering.CAPACITY,
+                                     'message': self.capacity.refuse_peering(sender)},
+                                   msg['from'], thid=msg['id'])
+            self.wire_client.send(sender, reply)
+            return ('declined', sender, reply['body'])
+        peer_desc = self.peers.descriptor(sender)
+        reply = self.host.offer(msg, peer_desc, self.clock())
+        published = self._flush_envelopes()
+        if not reply['type'].endswith('/offer'):
+            self.wire_client.send(sender, reply)
+            return ('declined', sender, reply['body'])
+        reply = dict(reply)
+        reply_body = dict(reply.get('body', {}))
+        if self.host.envelopes.get(sender):
+            reply_body['envelope_event'] = self.host.envelopes[sender]
+        reply['body'] = reply_body
+        mine = self.host.envelopes.get(sender)
+        self.grants.put(sender, grants_mod.ISSUED, self.host.issued[sender],
+                        reply['body']['grant_envelope'], self.clock(),
+                        event=mine, env_created_at=mine['created_at'] if mine else None)
+        self.wire_client.send(sender, reply)
+        for cb in self.on_grant_issued:
+            cb(sender, 'offer', reply['body']['grant_envelope'], (self.host.issued.get(sender) or {}).get('tier'))
+        return ('offered', sender, published)
+
+    def handle_accept(self: PeeringShape, inbound: Any, sender: str) -> tuple[Any, ...]:
+        msg = getattr(inbound, 'message', inbound)
+        body = msg.get('body')
+        if not isinstance(body, dict):
+            return ('ignored', sender, 'malformed body')
+        held = self.grants.get(sender, grants_mod.ISSUED)
+        if held is None or held['status'] != 'live':
+            return ('ignored', sender, 'accept from a node this node did not offer to')
+        grant = self._take_received(msg['body']['grant_envelope'], sender, msg['body'].get('envelope_event'))
+        for peered in self.on_peered:
+            peered(sender, 'acceptor', msg['body'].get('selected_transport'))
+        return ('peered', sender, grant)
+
+    def handle_amend(self: PeeringShape, inbound: Any, sender: str) -> tuple[Any, ...]:
+        msg = getattr(inbound, 'message', inbound)
+        body = msg.get('body')
+        if not isinstance(body, dict):
+            return ('ignored', sender, 'malformed body')
+        new_id = msg['body'].get('new_grant_envelope')
+        if not new_id:
+            self._refuse('amend', 'no new grant named', sender)
+            return ('ignored', sender, 'amend without a new grant')
+        held = self.grants.get(sender, grants_mod.RECEIVED)
+        if held is None or held['status'] != 'live':
+            self._refuse('amend', 'from a node whose grant this node does not hold', sender,
+                         {'named': new_id[:16]})
+            return ('ignored', sender, 'amend from a node whose grant this node does not hold')
+        was = held['envelope_id']
+        try:
+            grant = self._take_received(new_id, sender, msg['body'].get('envelope_event'))
+        except Exception as e:
+            self._refuse('amend', 'the grant it names could not be taken up', sender,
+                         {'named': new_id[:16], 'error': '%s: %s' % (type(e).__name__, e)})
+            return ('ignored', sender, 'amend names a grant this node could not take up: %s' % e)
+        now_held = self.grants.get(sender, grants_mod.RECEIVED)
+        if now_held is not None and now_held['envelope_id'] == was and was != new_id:
+            self._refuse('amend', 'refused as older than the grant already held', sender,
+                         {'named': new_id[:16], 'holding': was[:16]})
+            return ('ignored', sender, 'amend is older than the grant held')
+        return ('amended', sender, grant)
+
+    def handle_terminate(self: PeeringShape, inbound: Any, sender: str) -> tuple[Any, ...]:
+        msg = getattr(inbound, 'message', inbound)
+        body = msg.get('body')
+        if not isinstance(body, dict):
+            return ('ignored', sender, 'malformed body')
+        self.grants.zero(sender, self.clock())
+        if sender in self.host.issued:
+            self.host.terminate(sender, reason='peer terminated')
+        return ('terminated', sender, msg['body'])
+
+    def serve(self: PeeringShape, stop: threading.Event, poll: float = 0.5) -> None:
+        """Handle inbound peering messages until stop is set; others go back to the inbox."""
+        while not stop.is_set():
+            inbound = self.transport.receive(timeout=poll)
+            if inbound is None:
+                continue
+            try:
+                done = self.handle(inbound)
+            except Exception as e:
+                sender = getattr(inbound, 'sender', '') if inbound is not None else ''
+                self.log.append(('error', sender, str(e)))
+                continue
+            if done is None:
+                try:
+                    self.transport.inbox.put_nowait(inbound)   # not peering; leave it for whoever is
+                except queue.Full:
+                    pass
+                time.sleep(poll)
+            else:
+                self.log.append(done)

node/planes/peering/peering/shape.py

@@ -0,0 +1,80 @@
+"""The shape of a Peering as its mixins see it.
+
+The one class is split across core.py and handshake.py, the same way
+node/reporter/ is: each mixin method annotates `self` as this Protocol so
+the checker knows what is on it without the mixins inheriting from one
+another. A declaration only; Peering satisfies it structurally.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, Mapping, Optional, Protocol, Sequence
+
+from fleetmesh_core.wire.interfaces import GrantPayload, NostrEvent, UnsignedNostrEvent
+
+from node.compartment import stores as st
+from node.storage import grants as grants_mod
+from node.compartment import Refusals
+
+
+class PeeringHost(Protocol):
+    """What the wire needs from the peering state machine - exactly this.
+
+    fleetmesh_core.peering.Node satisfies it, and so does WireNode, which is
+    what Peering builds when none is given. The members are the whole of the
+    reach: the four tables the handshake reads and writes, the five message
+    writers, and the one method WireNode makes real (`_publish_envelope`).
+    A test may hand in anything with these members; nothing else on the
+    core Node is touched (review R11).
+    """
+    policy: Any
+    issued: dict[str, GrantPayload]
+    envelopes: dict[str, NostrEvent | UnsignedNostrEvent]
+    threads: dict[str, str]
+    digest_mismatch: dict[str, str]
+    published: list[NostrEvent]
+
+    def _msg(self, kind: str, body: Mapping[str, Any], to: str, thid: Optional[str] = None) -> Mapping[str, Any]: ...
+    def propose(self, to_did: str, want: Sequence[Mapping[str, Any]], offer: Sequence[Mapping[str, Any]],
+                budget_self: Mapping[str, Any], pow_event: Optional[str] = None,
+                pow_bits: Optional[int] = None) -> Mapping[str, Any]: ...
+    def offer(self, proposal: Mapping[str, Any], peer_descriptor: Optional[NostrEvent], now: int) -> Mapping[str, Any]: ...
+    def accept(self, offer: Mapping[str, Any], peer_did: str, want: Sequence[Mapping[str, Any]], now: int) -> Mapping[str, Any]: ...
+    def terminate(self, peer_pubkey: str, reason: str = 'operator', grace_seconds: int = 0) -> Mapping[str, Any]: ...
+    def disclose(self, query: Optional[list[dict[str, str]]] = None) -> dict[str, list[dict[str, str]]]: ...
+    def _publish_envelope(self, subject: str, grant: GrantPayload, now: Optional[int]) -> NostrEvent | UnsignedNostrEvent: ...
+
+
+class PeeringShape(Protocol):
+    TROUBLE_WINDOW: int
+    refusals: Refusals
+    capacity: Optional[Any]
+    _reconciled: Any
+    ks: Any
+    descriptor: Any
+    peers: Any
+    transport: Any
+    wire_client: Any
+    relays: list[str]
+    grants: grants_mod.GrantStore
+    clock: Callable[[], int]
+    timeout: float
+    host: PeeringHost
+    log: st.Ring[tuple[Any, ...]]
+    on_grant_issued: list[Callable[[str, str, str, Optional[str]], Any]]
+    on_peered: list[Callable[[str, str, Optional[str]], Any]]
+
+    # core.py
+    def _flush_envelopes(self) -> dict[str, dict[str, tuple[bool, str]]]: ...
+    def _fetch_envelope(self, envelope_id: Optional[str], issuer_pk: str) -> NostrEvent: ...
+    def _refuse(self, kind: str, why: str, subject: Optional[str] = None,
+                detail: Optional[Mapping[str, Any]] = None) -> Any: ...
+    def _take_received(self, envelope_id: Optional[str], issuer_pk: str,
+                       envelope_event: Optional[Mapping[str, Any]] = None) -> GrantPayload: ...
+
+    # handshake.py
+    def handle(self, inbound: Any) -> Optional[tuple[Any, ...]]: ...
+    def handle_discover(self, inbound: Any) -> Optional[tuple[Any, ...]]: ...
+    def handle_propose(self, inbound: Any, sender: str) -> tuple[Any, ...]: ...
+    def handle_accept(self, inbound: Any, sender: str) -> tuple[Any, ...]: ...
+    def handle_amend(self, inbound: Any, sender: str) -> tuple[Any, ...]: ...
+    def handle_terminate(self, inbound: Any, sender: str) -> tuple[Any, ...]: ...

node/planes/peering/peering/types.py

@@ -0,0 +1,39 @@
+"""Types and records for the Peering compartment."""
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional, TypedDict
+
+from fleetmesh_core.wire.interfaces import GrantPayload, NostrEvent
+
+
+class Issued(TypedDict):
+    """What `Peering.issue` hands back: the signed kind 30801, the grant it
+    wraps, what each relay said to it, and why it was written."""
+    envelope: NostrEvent
+    payload: GrantPayload
+    published: dict[str, dict[str, tuple[bool, str]]]
+    cause: str
+
+
+class PeeringDecision(TypedDict, total=False):
+    """Result of deciding a grant pending next epoch boundary."""
+    payload: Mapping[str, Any]
+    effective_from: int
+
+
+class PeeringStateReport(TypedDict, total=False):
+    """The report Peering.state() gives of itself."""
+    peers: int
+    reconciled: dict[str, int]
+    refused: int
+    digest_mismatch: dict[str, str]
+
+
+class PeeringResultDetail(TypedDict, total=False):
+    """Result of running propose against a peer."""
+    envelope: Optional[NostrEvent]
+    payload: Optional[GrantPayload]
+    published: dict[str, dict[str, tuple[bool, str]]]
+    cause: str
+    selected_transport: Optional[str]
+    reason: Optional[str]

node/planes/peering/reporter/__init__.py

@@ -0,0 +1,42 @@
+"""Reports and standing over the wire.
+
+One rule shapes all of this and is worth stating first: a report a reader will
+discard must not be published. The specification makes a kind 30802 admissible
+only if every evidence tag resolves to an event the subject itself signed, and
+readers count an inadmissible report as unsupported against the reporter. So
+publish() checks its own report against fleetmesh_core.peering.reports.admissible() before it goes
+out, and keeps it local if it fails. See node/README.md for what that rules
+out today, which is most of it.
+
+Findings come from two places: a window the budget evaluated, and a session
+the sync layer ran. Each is a verdict of fleetmesh_core/'s arithmetic against one peer
+under one grant this node issued. What happens next is the specification's
+complaint rule, executed: S1 and S2 are presented to the subject as a
+complaint/1.0/notice and published only after a window has passed; S3 and S4
+are published at once. The report is the kind 30802 fleetmesh_core.peering.reports.build()
+makes, signed by this node and put on the relays with its evidence.
+
+The other side of the same coin is reading: fetch the reports about a node,
+keep the admissible ones, weight each by what this node itself knows of the
+reporter, and fold them into a view with fleetmesh_core.accounting.window. A reader that holds no
+grant to the reporter weights it at zero, so a stranger's report moves
+nothing.
+
+standing/1.0 rides here too: an ask goes out through the transport, a tell
+comes back from the peer's ledger, and inbound asks are answered from ours
+only about nodes we hold a grant to.
+
+Split the way node/budget/ and node/compute/ are: core.py holds construction
+and the Compartment contract, findings.py/publish.py/reading.py are the mixins
+for each concern, and shape.py is the structural Protocol the checker types
+`self` against inside each mixin.
+"""
+from __future__ import annotations
+
+from .constants import FINDING_WINDOWS, KEEP_UNPUBLISHABLE, LIMIT_METRICS, PUBLISH_TRIES, REPORT_TTL
+from .core import Reporter
+from .finding import Finding
+
+__all__ = [
+    'FINDING_WINDOWS', 'KEEP_UNPUBLISHABLE', 'LIMIT_METRICS', 'PUBLISH_TRIES', 'REPORT_TTL', 'Reporter', 'Finding',
+]

node/planes/peering/reporter/constants.py

@@ -0,0 +1,29 @@
+"""The reporter's fixed numbers, in one place so the mixins and core import
+them without importing each other.
+"""
+from __future__ import annotations
+
+REPORT_TTL: int = 30 * 86400
+# A finding that never became a report is dropped when the accounting under it
+# is gone. `Budget.KEEP_WINDOWS` is how long a window's receipts, meters and
+# evaluation are kept, and past that this node cannot substantiate a finding
+# about that window to anyone, including itself. The same number, stated here
+# rather than imported, because budget imports nothing from this module and the
+# dependency must not start running the other way.
+FINDING_WINDOWS: int = 24 * 7
+# How many times a finding that could not be published is tried again, and how
+# many of those refusals are kept for the operator to read.
+PUBLISH_TRIES: int = 3
+KEEP_UNPUBLISHABLE: int = 200
+# What the reporter keeps of what it signed: the newest KEEP_SIGNED of each
+# kind (30802 reports, 30385 relay scores, 1985 labels). The relays hold them;
+# these copies are for `state` and the operator. KEEP_THREADS complaint
+# threads of each side, the bound notices_in was cut to by hand. KEEP_LOG of
+# the log, as many as the node's own.
+KEEP_SIGNED: int = 256
+KEEP_THREADS: int = 1000
+KEEP_LOG: int = 500
+LIMIT_METRICS: tuple[str, ...] = (
+    'conn_rate', 'req', 'events_in', 'bytes_in', 'bytes_out',
+    'blob_bytes', 'sync_ranges', 'errors', 'dup_ratio'
+)