fleetmesh-node 0.2.0__py3-none-any.whl

node/transport/relay_rung/inbound.py

@@ -0,0 +1,161 @@
+"""Inbound side of the relay rung: a wrap off a relay becomes a message, or a
+drop with a reason. Dedup, unwrap, reassemble fragments, open the envelope
+by the rule every rung shares (didcomm_inbound), then route to the thread
+waiter or the inbox.
+"""
+from __future__ import annotations
+
+import json
+import queue
+import time
+from typing import TYPE_CHECKING, Any, Mapping, Optional
+
+from fleetmesh_core.crypto import giftwrap
+
+from .. import didcomm_inbound
+from .. import const
+from ..const import Inbound, _foreign
+from .types import Partial
+
+
+if TYPE_CHECKING:
+    from .shape import RelayRungShape
+
+
+class InboundMixin:
+    def _remember(self: RelayRungShape, wid: str, kind: Optional[int] = None) -> bool:
+        """True if this wrap is new. The set is capped: a wrap older than the
+        cap has aged past the relay's replay horizon anyway. A stored wrap is
+        also remembered on disk, because it outlives this process."""
+        with self._lock:
+            if wid in self._seen:
+                return False
+            if kind == giftwrap.WRAP_STORED and self.seen_store is not None and self.seen_store[0](wid):
+                return False
+            self._seen.add(wid)
+            self._seen_order.append(wid)
+            while len(self._seen_order) > self.seen_max:
+                self._seen.discard(self._seen_order.popleft())
+        if kind == giftwrap.WRAP_STORED and self.seen_store is not None:
+            self.seen_store[1](wid, self.clock())
+        return True
+
+    def _deliver(self: RelayRungShape, wrap: Any) -> None:
+        if not isinstance(wrap, dict) or not isinstance(wrap.get('id'), str):
+            self._drop('wrap: not an event', None)
+            return
+        wid: str = wrap['id']
+        # Counted by kind before anything else can discard it. Ephemeral wraps
+        # (21059) carry receipts and sync; stored wraps (1059) carry the four
+        # messages that must survive an offline peer, an amended grant among
+        # them. When every peering on a mesh stopped taking up amends while
+        # receipts kept flowing, nothing in this node could answer whether a
+        # stored wrap had arrived at all, which is the first question.
+        self.wraps_in[wrap.get('kind')] += 1
+        if not self._remember(wid, wrap.get('kind')):
+            # A wrap already seen used to return silently. A relay replays
+            # stored wraps for two days, so this is ordinary - but it is also
+            # exactly how a message that was seen and never acted on becomes
+            # invisible for ever.
+            self.wraps_seen_again[wrap.get('kind')] += 1
+            return
+        try:
+            jwe, seal_pk = giftwrap.unwrap(wrap, self.ks.node_sk, now=self.clock())
+        except (giftwrap.GiftWrapError, ValueError, TypeError, KeyError) as e:
+            self._drop('wrap: %s' % e, wid)
+            return
+        if isinstance(jwe, dict) and 'frag' in jwe:
+            assembled = self._reassemble(jwe, seal_pk)
+            if assembled is None:
+                return                      # more fragments to come
+            jwe = assembled
+        if not isinstance(jwe, dict) or 'protected' not in jwe:
+            # Said apart from malformed traffic when it can be. NIP-59 does not
+            # namespace what is inside a wrap, so kind 21059 addressed to this
+            # key is shared ground with every other protocol that uses it - one
+            # machine running two of them under one key has each daemon's
+            # subscription receiving the other's envelopes. It fails closed
+            # either way, but one reason for both had an operator reading
+            # somebody else's healthy traffic as a peer sending malformed
+            # envelopes, and the count is what they read first.
+            self._drop(_foreign(jwe), wid)
+            return
+        # Decrypt and check that the names agree, by the one rule every rung
+        # shares (didcomm_inbound). The seal signer is the third name here.
+        inbound, why = didcomm_inbound.open_inbound(jwe, self.ks, self.peers, wid, seal_pk=seal_pk)
+        if inbound is None:
+            self._drop(why or 'envelope: refused', wid)
+            return
+        message = inbound.message
+        thid = message.get('thid')
+        # The three names agree, so this is the peer speaking. Everything
+        # below is the acknowledgment machinery, which lives here below the
+        # protocols because it is about the transport keeping its word.
+        self.heard[seal_pk] = self.clock()
+        if isinstance(message.get('ack'), list):
+            self._acknowledged(message['ack'])
+        asks = message.get('please_ack')
+        if (isinstance(asks, list) and ('' in asks or message['id'] in asks)
+                and message.get('type') != const.EMPTY_TYPE):
+            # Never honour a request that arrives on a pure ack, and never
+            # more than once per message - the wrap dedup above already
+            # makes a replay not a message.
+            self._acks.put((message['id'], seal_pk))
+        if message.get('type') == const.EMPTY_TYPE:
+            # Headers only, by definition. Consumed here; no handler wants it.
+            return
+        with self._lock:
+            waiter = self._waiting.get(thid) if thid else None
+        try:
+            (waiter if waiter is not None else self.inbox).put_nowait(inbound)
+        except queue.Full:
+            self._drop('inbox full', wid)
+            return
+
+    def _reassemble(self: RelayRungShape, frag: Mapping[str, Any], seal_pk: str) -> Optional[Any]:
+        """Collect fragments by id and sender; the JWE once all have arrived."""
+        try:
+            fid, i, n, data = frag['frag'], int(frag['i']), int(frag['n']), frag['data']
+        except (KeyError, ValueError, TypeError):
+            self._drop('malformed fragment', None)
+            return None
+        if not (0 < n <= const.MAX_FRAGMENTS and 0 <= i < n) or not isinstance(data, str):
+            self._drop('fragment out of range', None)
+            return None
+        if not isinstance(fid, str) or len(fid) > 64 or len(data) > const.FRAGMENT_BYTES + 16:
+            self._drop('fragment out of range', None)
+            return None
+        key = (seal_pk, fid)
+        with self._lock:
+            # drop assemblies nobody finished in ten minutes
+            for k in [k for k, v in self._partials.items() if time.time() - v['at'] > 600]:
+                self._partials.pop(k, None)
+            parts = self._partials.get(key)
+            if parts is None:
+                mine = sum(1 for k in self._partials if k[0] == seal_pk)
+                if mine >= const.PARTIALS_PER_SENDER or len(self._partials) >= const.PARTIALS_MAX:
+                    self._drop('fragment: too many unfinished envelopes', None)
+                    return None
+                parts = self._partials[key] = Partial(n=n, parts={}, at=time.time())
+            if parts['n'] != n:
+                self._drop('fragment: count changed mid-envelope', None)
+                self._partials.pop(key, None)
+                return None
+            parts['parts'][i] = data
+            if len(parts['parts']) < n:
+                return None
+            self._partials.pop(key, None)
+        try:
+            return json.loads(''.join(parts['parts'][k] for k in range(n)))
+        except ValueError:
+            self._drop('reassembled fragments are not JSON', None)
+            return None
+
+
+    def receive(self: RelayRungShape, timeout: Optional[float] = None) -> Optional[Inbound]:
+        """The next unsolicited message, or None on timeout."""
+        try:
+            return self.inbox.get(timeout=timeout)
+        except queue.Empty:
+            return None
+

node/transport/relay_rung/ledger.py

@@ -0,0 +1,104 @@
+"""The acknowledgment ledger: stored messages sent and not yet answered.
+
+A relay's OK is its word about itself, not about delivery. Every stored
+message asks for an ack (DIDComm `please_ack`) and is held here until one
+arrives; `sweep()` turns silence from a peer that has since spoken into a
+verdict the operator can read.
+"""
+from __future__ import annotations
+
+import os
+import queue
+from typing import TYPE_CHECKING, Any, Optional, Sequence
+
+from .. import const
+from ..const import TransportError
+from .types import AckVerdict, Verdict
+
+
+if TYPE_CHECKING:
+    from .shape import RelayRungShape
+
+
+class LedgerMixin:
+    def _ack(self: RelayRungShape, mid: str, peer: str) -> None:
+        """A pure acknowledgment: the empty message with an `ack` header."""
+        msg = {'id': 'ack-' + os.urandom(6).hex(), 'type': const.EMPTY_TYPE, 'thid': mid, 'ack': [mid], 'body': {}}
+        # Counted before the send and taken back if it raised, the way the
+        # relay face counts what it refuses. The peer's `sweep` clears on the
+        # ack itself rather than on this number, so nothing on the wire turns
+        # on the order - but health is read by another thread, and a caller
+        # that has seen the ack arrive and then reads 0 acks out has been told
+        # the wrong thing rather than told it late.
+        self.acks_out += 1
+        try:
+            self.send(msg, peer)
+        except TransportError as e:
+            self.acks_out -= 1
+            self._drop('ack not sent: %s' % e, None)
+
+    def _acker(self: RelayRungShape) -> None:
+        """Acks are sent off the relay thread, because a send publishes to
+        every relay with a timeout each and the subscription must not wait."""
+        while not self._stop.is_set():
+            try:
+                mid, peer = self._acks.get(timeout=0.5)
+            except queue.Empty:
+                continue
+            self._ack(mid, peer)
+
+    def _acknowledged(self: RelayRungShape, ids: Sequence[Any]) -> None:
+        for mid in ids:
+            if not isinstance(mid, str):
+                continue
+            with self._lock:
+                entry = self.awaiting.pop(mid, None)
+            if entry is None:
+                continue
+            self.acked[entry['type']] += 1
+            self.acks_in += 1
+            if self.ack_store is not None:
+                self.ack_store.drop_awaiting(mid)
+
+    def sweep(self: RelayRungShape, now: Optional[int] = None) -> list[AckVerdict]:
+        """Judge what is still unacknowledged, and return the new verdicts.
+
+        A message is undelivered when the peer has been heard from at least
+        ACK_SLACK after it was sent, that hearing is ACK_GRACE old, and no ack
+        has come: the peer was up, a relay serving the wrap would have handed
+        it over, and the peer said nothing about it. A peer not heard from is
+        not a verdict; it may simply be away. Past ACK_EXPIRE the relay would
+        not serve the wrap anyway, and the entry is dropped as expired.
+        """
+        now_val = int(now if now is not None else self.clock())
+        out: list[AckVerdict] = []
+        with self._lock:
+            for mid, e in list(self.awaiting.items()):
+                heard = self.heard.get(e['peer'])
+                if heard is not None and heard >= e['at'] + const.ACK_SLACK:
+                    e['heard_at'] = heard if e['heard_at'] is None else e['heard_at']
+                verdict: Optional[Verdict] = None
+                if e['heard_at'] is not None and now_val >= e['heard_at'] + const.ACK_GRACE:
+                    verdict = 'unacknowledged'
+                elif now_val >= e['at'] + const.ACK_EXPIRE:
+                    verdict = 'expired'
+                if verdict is None:
+                    continue
+                del self.awaiting[mid]
+                v = AckVerdict(peer=e['peer'], type=e['type'], at=e['at'], relays=e['relays'],
+                               heard_at=e['heard_at'], mid=mid, verdict=verdict, at_verdict=now_val)
+                self.unacked.append(v)
+                out.append(v)
+            self._unacked_new.extend(out)
+        if self.ack_store is not None:
+            for v in out:
+                self.ack_store.drop_awaiting(v['mid'])
+        return out
+
+    def take_unacked(self: RelayRungShape) -> list[AckVerdict]:
+        """The verdicts since the last call, for the compartment that records them."""
+        with self._lock:
+            out: list[AckVerdict] = self._unacked_new
+            self._unacked_new = list[AckVerdict]()
+        return out
+

node/transport/relay_rung/listen.py

@@ -0,0 +1,121 @@
+"""The listening side of the relay rung: one subscription per relay for the
+life of the node, with reconnects the operator can read about, and the
+readiness check everything that is about to cause traffic waits on.
+"""
+from __future__ import annotations
+
+import threading
+import time
+from typing import TYPE_CHECKING, Any, Optional
+
+from ...protocols.nostr import client as relay
+from .. import const
+from . import wire
+
+
+if TYPE_CHECKING:
+    from .shape import RelayRungShape
+
+
+class ListenMixin:
+    def start(self: RelayRungShape, since: Optional[int] = None) -> Any:
+        # A wrap's created_at is skewed up to two days into the past, so a
+        # subscription that starts "now" misses most of them. Whatever the
+        # caller asks for, the filter reaches back at least that far.
+        floor = wire.since_floor(self.clock())
+        since_val = floor if since is None else min(since, floor)
+        for url in self.relays:
+            t = threading.Thread(target=self._listen, args=(url, since_val), daemon=True)
+            t.start()
+            self._threads.append(t)
+        t = threading.Thread(target=self._acker, daemon=True)
+        t.start()
+        self._threads.append(t)
+        return self
+
+    def stop(self: RelayRungShape) -> None:
+        self._stop.set()
+
+
+    def _listen(self: RelayRungShape, url: str, since: int) -> None:
+        """One relay's subscription, for the life of the node.
+
+        This used to swallow every error and retry once a second, silently,
+        with the same `since` it started with. A relay that was down for a
+        day was dialled eighty-six thousand times and nobody was told; one
+        that came back replayed everything since the node started. The
+        state is kept where the operator can read it, the retry backs off,
+        and each reconnect asks only for what the skew allowance requires.
+        """
+        h = self.health[url]
+        backoff = 1.0
+        first = True
+        while not self._stop.is_set():
+            if not first:
+                since = wire.since_floor(self.clock())
+            first = False
+            filt = wire.subscription(self.ks.node_pk, since)
+            def _on_late_eose(_sid: str) -> None:
+                h['confirmed'] = True
+                if h.get('last_error') and 'no EOSE in' in str(h['last_error']):
+                    h['last_error'] = None
+
+            r = relay.Relay(url, timeout=5.0, auth_signer=self._sign_auth, on_eose=_on_late_eose)
+            try:
+                sid = r.connect().subscribe([filt], ready=True)
+                # `connected` is the socket; `confirmed` is the relay's own
+                # EOSE. They are reported apart because a subscription that
+                # was sent and never acknowledged still carries events, so
+                # tearing it down would be worse than saying so.
+                h['connected'] = True
+                h['confirmed'] = r.confirmed(sid)
+                h['since'] = self.clock()
+                h['last_error'] = (None if r.confirmed(sid)
+                                   else 'the subscription was not acknowledged: no EOSE in %.0fs' % 5.0)
+                backoff = 1.0
+                for wrap in r.events(sid):
+                    if self._stop.is_set():
+                        break
+                    h['last_event_at'] = self.clock()
+                    try:
+                        self._deliver(wrap)
+                    except Exception as e:          # a bug in delivery drops one wrap, not the relay
+                        self._drop('delivery failed: %s: %s' % (type(e).__name__, e),
+                                   wrap.get('id') if isinstance(wrap, dict) else None)
+                if not self._stop.is_set():
+                    h['last_error'] = 'subscription ended'
+            except Exception as e:
+                h['last_error'] = '%s: %s' % (type(e).__name__, str(e)[:120])
+            finally:
+                r.close()
+                h['confirmed'] = False
+                if h['connected']:
+                    h['connected'] = False
+                    h['reconnects'] += 1
+            if not self._stop.is_set():
+                self._stop.wait(backoff)
+                backoff = min(backoff * 2, const.BACKOFF_MAX)
+
+
+    def listening(self: RelayRungShape) -> int:
+        """How many relays have acknowledged this node's own subscription."""
+        return sum(1 for h in self.health.values() if h['confirmed'])
+
+    def wait_listening(self: RelayRungShape, seconds: float = 10.0, at_least: int = 1) -> bool:
+        """Block until `at_least` relays have acknowledged the subscription.
+
+        `start()` returns as soon as the threads exist, which is not the same as
+        being reachable. Between the two, a live wrap addressed to this node is
+        fanned out to nobody and no relay keeps a copy, because kind 21059 is
+        ephemeral - the node never learns there was anything to miss. Anything
+        about to cause traffic waits here instead of sleeping and hoping: a
+        node starting up, or a test that is about to publish.
+
+        False if the wait ran out, which is a relay problem and is already on
+        the health of the relay that caused it.
+        """
+        deadline = time.time() + seconds
+        while time.time() < deadline and self.listening() < at_least:
+            time.sleep(0.05)
+        return self.listening() >= at_least
+

node/transport/relay_rung/outbound.py

@@ -0,0 +1,181 @@
+"""Outbound side of the relay rung: address, encrypt, wrap, publish; and the
+thread waiters request()/converse() use to wait for an answer.
+"""
+from __future__ import annotations
+
+import queue
+from typing import TYPE_CHECKING, Any, Mapping, Optional, cast
+
+from fleetmesh_core.identity import didcomm, relaylist
+from fleetmesh_core.identity.did import did_nostr
+from ...protocols.nostr import client as relay
+from .. import const
+from ..const import Inbound, TransportError
+from . import cooldown, wire
+from .types import AwaitingEntry, OutboundMessage
+
+
+if TYPE_CHECKING:
+    from .shape import RelayRungShape
+
+
+class OutboundMixin:
+    def inbox_relays(self: RelayRungShape, to_pubkey: str) -> list[str]:
+        """Where a stored wrap for this peer goes: the relays its kind 10050
+        names (NIP-17), and this node's own when it has published none or
+        they cannot be read. The peer's inbox first, because that is where
+        it will look; ours as well, because a peer with no list reads its
+        descriptor relays and those are usually ours."""
+        now = self.clock()
+        held = self._dm_relays.get(to_pubkey)
+        if held is not None and now - held[1] < const.DM_RELAYS_TTL:
+            theirs = held[0]
+        else:
+            theirs = []
+            if self.relays:
+                try:
+                    found = relay.query_all(self.relays, [relaylist.filter_for(to_pubkey)], self.timeout)
+                    newest = max(found, key=lambda e: int(e.get('created_at', 0)), default=None)
+                    theirs = relaylist.dm_relays(newest) if newest is not None else []
+                except Exception:
+                    theirs = []
+            self._dm_relays[to_pubkey] = (theirs, now)
+        return theirs + [r for r in self.relays if r not in theirs]
+
+
+    def send(self: RelayRungShape,
+        message: Mapping[str, Any],
+        to_pubkey: str,
+        anonymous: bool = False,
+        stored: bool = False,
+    ) -> dict[str, tuple[bool, str]]:
+        """Encrypt, wrap and publish. Returns {relay: (accepted, note)}.
+
+        `stored` sends kind 1059, which relays keep, for the messages the
+        specification says must survive the recipient being offline: a grant
+        amendment, a complaint notice, a window close. Everything else is
+        kind 21059 and gone if nobody is listening, which is the point.
+        """
+        their = self.peers.agreement(to_pubkey)
+        if their is None:
+            raise TransportError('no live descriptor for %s; cannot address an envelope' % to_pubkey[:16])
+        msg_dict = cast(OutboundMessage, dict(message))  # the caller's message, addressed below
+        msg_dict.setdefault('from', self.ks.did)
+        msg_dict.setdefault('to', [did_nostr(to_pubkey)])
+        msg_dict.setdefault('created_time', self.clock())
+        if stored and isinstance(msg_dict.get('id'), str):
+            # "" is DIDComm's shorthand for this message. A pure ack never
+            # asks for one, so this cannot start a circle.
+            msg_dict['please_ack'] = ['']
+        kid = did_nostr(to_pubkey) + '#agree'
+        sender = None if anonymous else (self.ks.kid('agreement'), self.ks.agreement_priv)
+        jwe = didcomm.encrypt(msg_dict, [(kid, their)], sender=sender)
+        held = stored and isinstance(msg_dict.get('id'), str)
+        if held:
+            # Held before the first relay is asked, not after the last one
+            # answers: a peer on the first relay acknowledges in tens of
+            # milliseconds, and an entry registered after the second relay's
+            # OK was being registered after the ack it waited for had come
+            # and gone. Which relays took it is filled in below.
+            entry = AwaitingEntry(peer=to_pubkey, type=str(msg_dict.get('type', ''))[-40:],
+                                  at=self.clock(), relays=[], heard_at=None)
+            with self._lock:
+                self.awaiting[msg_dict['id']] = entry
+        results: dict[str, tuple[bool, str]] = {}
+        wanted = self.inbox_relays(to_pubkey) if stored else self.relays
+        targets = self.cooldown.open(wanted)
+        for url in wanted:
+            cooling = self.cooldown.holding(url)
+            if cooling is not None:
+                # Not asked, so not refused; the result says why it was skipped.
+                results[url] = (False, 'cooling until %d: %s' % (cooling['until'], cooling['why']))
+        for payload in wire.fragments(jwe):
+            wrap = wire.make_wrap(payload, self.ks.node_sk, to_pubkey, self.clock(), stored)
+            took = relay.publish_all(targets, wrap, self.timeout, auth_signer=self._sign_auth)
+            for url, r in took.items():
+                if r[0]:
+                    self.cooldown.accepted(url)
+                else:
+                    cooling = self.cooldown.refused(url, r[1] or '')
+                    if cooling is not None:
+                        self._drop('relay cooled: %s until %d (strike %d) %s'
+                                   % (url, cooling['until'], cooling['strikes'], r[1]), wrap['id'])
+                if url not in results:
+                    results[url] = r
+                else:
+                    prev_ok, prev_note = results[url]
+                    curr_ok, curr_note = r
+                    results[url] = (prev_ok and curr_ok, curr_note if not curr_ok else prev_note)
+            refused = {u: r[1] or 'no reason' for u, r in took.items()
+                       if not r[0] and not cooldown.is_throttle(r[1] or '')}
+            if refused and not any(r[0] for r in took.values()):
+                # No relay took this fragment, so the envelope never leaves and
+                # nothing else in the protocol will ever say so: the peer times
+                # out and the session is merely aborted. One relay of several
+                # refusing while another accepts is that relay's weather, kept
+                # in its health row; a throttle is recorded above as the
+                # cooling it caused.
+                self._drop('publish refused: %s' % '; '.join('%s %s' % kv for kv in sorted(refused.items())), wrap['id'])
+            elif refused:
+                for url, why in refused.items():
+                    self.faults.record('relay flaked: %s %s' % (url, why), wrap['id'])
+        if held:
+            accepted = sorted(u for u, r in results.items() if r[0])
+            with self._lock:
+                still = self.awaiting.get(msg_dict['id'])
+                if still is not None:
+                    if accepted:
+                        still['relays'] = accepted
+                    else:
+                        # Nowhere took it, so it never left; the refused
+                        # publish above is the record and there is nothing
+                        # to wait for.
+                        del self.awaiting[msg_dict['id']]
+                        still = None
+            if still is not None and self.ack_store is not None:
+                self.ack_store.put_awaiting(msg_dict['id'], to_pubkey, still['type'], still['at'], accepted)
+        return results
+
+
+    def request(self: RelayRungShape,
+        message: Mapping[str, Any],
+        to_pubkey: str,
+        timeout: float = 30.0,
+        anonymous: bool = False,
+    ) -> Optional[Inbound]:
+        """Send and wait for the reply threaded on this message's id."""
+        return self.converse(message, to_pubkey, message['id'], timeout, anonymous)
+
+    def converse(self: RelayRungShape,
+        message: Mapping[str, Any],
+        to_pubkey: str,
+        thid: str,
+        timeout: float = 30.0,
+        anonymous: bool = False,
+    ) -> Optional[Inbound]:
+        """Send and wait for the next message on an existing thread. A sync
+        session keeps one thread open across many exchanges, so the waiter is
+        keyed by the thread and not by the message just sent."""
+        q = self.listen(thid)
+        try:
+            self.send(message, to_pubkey, anonymous=anonymous)
+            try:
+                return q.get(timeout=timeout)
+            except queue.Empty:
+                return None
+        finally:
+            self.unlisten(thid)
+
+    def listen(self: RelayRungShape, thid: str) -> queue.Queue[Inbound]:
+        """Route messages on this thread to a private queue instead of the inbox."""
+        with self._lock:
+            q = self._waiting.get(thid)
+            if q is None:
+                q = self._waiting[thid] = queue.Queue()
+        return q
+
+    def unlisten(self: RelayRungShape, thid: str) -> None:
+        with self._lock:
+            self._waiting.pop(thid, None)
+
+    # ---- inbound -----------------------------------------------------------

node/transport/relay_rung/shape.py

@@ -0,0 +1,71 @@
+"""What the relay rung's mixins may assume about `self`.
+
+Declared once so outbound.py, listen.py, inbound.py and ledger.py can call
+each other's methods and read the shared state without inheriting from one
+another. core.RelayRung is the one class that satisfies it.
+"""
+from __future__ import annotations
+
+import queue
+import threading
+from typing import Any, Callable, Counter, Deque, Mapping, Optional, Protocol
+
+from ..const import Inbound
+from ...interfaces import NostrEvent, RelayHealthRow
+from ..ladder import FaultLog
+from .cooldown import RelayCooldown
+from .types import AckVerdict, AwaitingEntry, Partial
+
+
+class RelayRungShape(Protocol):
+    ks: Any
+    peers: Any
+    relays: list[str]
+    clock: Callable[[], int]
+    timeout: float
+    seen_max: int
+    inbox: queue.Queue[Inbound]
+    _waiting: dict[str, queue.Queue[Inbound]]
+    _lock: threading.Lock
+    _stop: threading.Event
+    _threads: list[threading.Thread]
+    health: dict[str, RelayHealthRow]
+    faults: FaultLog
+    cooldown: RelayCooldown
+    # ledger
+    ack_store: Optional[Any]
+    awaiting: dict[str, AwaitingEntry]
+    heard: dict[str, int]
+    acked: Counter[str]
+    acks_in: int
+    acks_out: int
+    unacked: Deque[AckVerdict]
+    _unacked_new: list[AckVerdict]
+    _acks: queue.Queue[tuple[str, str]]
+    # inbound
+    seen_store: Optional[tuple[Callable[[str], bool], Callable[[str, int], None]]]
+    wraps_in: Counter[Optional[int]]
+    wraps_seen_again: Counter[Optional[int]]
+    _seen: set[str]
+    _seen_order: Deque[str]
+    _partials: dict[tuple[str, str], Partial]
+    # outbound
+    _dm_relays: dict[str, tuple[list[str], int]]
+
+    def _drop(self, reason: str, wrap_id: Optional[str]) -> None: ...
+    def _sign_auth(self, relay_url: str, challenge: str) -> NostrEvent: ...
+    def send(self, message: Any, to_pubkey: str, anonymous: bool = False,
+             stored: bool = False) -> dict[str, tuple[bool, str]]: ...
+    def listen(self, thid: str) -> queue.Queue[Inbound]: ...
+    def unlisten(self, thid: str) -> None: ...
+    def _deliver(self, wrap: Any) -> None: ...
+    def _acknowledged(self, ids: Any) -> None: ...
+    def _ack(self, mid: str, peer: str) -> None: ...
+    def listening(self) -> int: ...
+    def _remember(self, wid: str, kind: Optional[int] = None) -> bool: ...
+    def _reassemble(self, frag: Mapping[str, Any], seal_pk: str) -> Optional[Any]: ...
+    def inbox_relays(self, to_pubkey: str) -> list[str]: ...
+    def converse(self, message: Any, to_pubkey: str, thid: str, timeout: float = 30.0,
+                 anonymous: bool = False) -> Optional[Inbound]: ...
+    def _listen(self, url: str, since: int) -> None: ...
+    def _acker(self) -> None: ...