Source code for fleetmesh_node.protocols.nostr.client

"""A nostr relay client: publish an event and wait for its OK, or query.

The only module in the node that speaks the relay wire (REQ/EVENT/OK/EOSE/
AUTH). Two kinds of caller: the relay rung (fleetmesh_node.transport.relay_rung), for
gift wraps to and from peers, and the control-plane publishers (descriptor,
presence, discovery, reports), for the node's own signed events. Neither is
the other's business, so they share this and nothing else.

The node talks to relays for three things: to publish its own descriptor,
grants and reports; to read other nodes' descriptors; and, as its default
transport, to send and receive gift wraps. Query collects until EOSE; a
subscription yields events as they arrive and is how the transport listens.
"""
from __future__ import annotations

import json
import logging
import os
import socket
import time
from typing import Any, Callable, cast, Iterator, Mapping, Optional, Sequence

from fleetmesh_node.interfaces import EventLike, NostrEvent, NostrFilter
from fleetmesh_node.transport import ws

log = logging.getLogger(__name__)


[docs]class RelayError(Exception): pass
# A subscription that receives nothing is either quiet or dead, and a socket # that was dropped without a close frame looks quiet forever. Past PING_AFTER # seconds of silence the client pings; past DEAD_AFTER with no frame back, # not even a pong, the subscription is declared dead and the listener # reconnects. PING_AFTER: float = 60.0 DEAD_AFTER: float = 150.0
[docs]class Relay:
[docs] def __init__( self, url: str, timeout: float = 15.0, auth_signer: Optional[Callable[[str, str], Optional[EventLike]]] = None, ping_after: float = PING_AFTER, dead_after: float = DEAD_AFTER, on_eose: Optional[Callable[[str], None]] = None, ) -> None: self.url: str = url self.timeout: float = timeout # Liveness thresholds are per connection so a test (or an operator # on a flaky link) sets them on the one Relay, not on the module. self.ping_after: float = ping_after self.dead_after: float = dead_after self.auth_signer: Optional[Callable[[str, str], Optional[EventLike]]] = auth_signer self.on_eose: Optional[Callable[[str], None]] = on_eose self.ws: Optional[ws.WebSocket] = None self._n: int = 0 self._subs: dict[str, list[NostrFilter | Mapping[str, Any]]] = {} self._pending: dict[str, list[NostrEvent]] = {} # events read while waiting for an EOSE self._confirmed: set[str] = set() # subscriptions the relay answered with an EOSE # NIP-42 is a property of the connection, not of one subscription or # one call: once this socket has answered a challenge every REQ on it # is read as this key. `_reissued` is the subscriptions sent again # after the AUTH, so the CLOSED that answers the first attempt is # recognised as stale rather than as a second refusal. self.authed: bool = False self._reissued: set[str] = set()
[docs] def connect(self) -> Relay: if self.ws is None: # Every way the handshake can fail is one answer to the caller: # the relay is not reachable. ws.connect raises OSError for the # socket (refused, timed out, DNS), ws.ConnectionClosed for a # peer that closed mid-handshake or sent an endless header, and # ConnectionError for a refused upgrade (both are OSError # subclasses; named so a reader need not know that). Callers # that catch RelayError must not see a bare ConnectionClosed. try: self.ws = ws.connect(self.url, self.timeout) except (OSError, ws.ConnectionClosed) as e: raise RelayError('%s: %s: %s' % (self.url, type(e).__name__, e)) from e if hasattr(self.ws.sock, 'settimeout'): self.ws.sock.settimeout(self.timeout) return self
[docs] def close(self) -> None: if self.ws is not None: self.ws.close() self.ws = None self._subs.clear() self._reissued.clear() self.authed = False
def _send(self, msg: list[Any]) -> None: self.connect() assert self.ws is not None self.ws.send_text(json.dumps(msg, separators=(',', ':'))) def _recv(self) -> list[Any]: assert self.ws is not None raw = self.ws.recv_text() try: msg = json.loads(raw) except ValueError: raise RelayError('relay sent something that is not JSON') if not isinstance(msg, list) or not msg: raise RelayError('relay sent a malformed message') return msg def _handle_auth(self, challenge: str) -> bool: """Sign and send a NIP-42 AUTH message if auth_signer is configured. Returns True if an AUTH response was sent. """ if self.auth_signer is not None: try: auth_ev = self.auth_signer(self.url, challenge) except Exception: # The signer is caller-supplied code (keystore, HSM, test # stub); a fault in it means "no AUTH", which the caller # sees as the relay refusing the subscription. Logged, since # a broken signer is a bug and not a relay condition. log.exception('relay %s: auth_signer failed', self.url) return False if auth_ev is not None: self._send(['AUTH', auth_ev]) self.authed = True return True return False def _challenged(self, challenge: str, sids: Sequence[str]) -> bool: """An AUTH challenge arrived while these subscriptions were open: answer it and send each of them again, once. A relay that gates a kind behind NIP-42 (strfry: `relay.auth.restrictedReadKinds`) answers a fully-gated REQ with AUTH *then* CLOSED, so by the time the CLOSED is read the re-issue is already on the wire.""" if not self._handle_auth(challenge): return False for sid in sids: if sid in self._subs and sid not in self._reissued: self._reissued.add(sid) self._send(['REQ', sid] + self._subs[sid]) return True def _closed(self, sid: str, reason: str) -> str: """What a CLOSED for an auth-gated subscription means on this connection. 'stale' - it answers the REQ sent before the AUTH; the re-issue is in flight. 'retry' - the connection is authed and this REQ has now been sent again. 'await' - no AUTH yet; the challenge should be the next frame. 'closed' - not an auth matter, or no signer: the subscription is gone. """ if 'auth-required' not in reason or self.auth_signer is None or sid not in self._subs: return 'closed' if sid in self._reissued: return 'stale' if self.authed: self._reissued.add(sid) self._send(['REQ', sid] + self._subs[sid]) return 'retry' return 'await' def _sub_id(self) -> str: self._n += 1 return 'sub-%d-%s' % (self._n, os.urandom(3).hex())
[docs] def publish(self, event: EventLike) -> tuple[bool, str]: """(accepted, message) for one event.""" self._send(['EVENT', event]) deadline = time.time() + self.timeout authed = False retried = False last_rejected_reason: Optional[str] = None while time.time() < deadline: msg = self._recv() if msg[0] == 'AUTH' and len(msg) > 1 and isinstance(msg[1], str): if self._handle_auth(msg[1]): authed = True if last_rejected_reason and 'auth-required' in last_rejected_reason and not retried: retried = True self._send(['EVENT', event]) continue if msg[0] == 'OK' and len(msg) > 2: if msg[1] == event['id']: accepted = bool(msg[2]) reason = msg[3] if len(msg) > 3 else '' if not accepted and 'auth-required' in reason: last_rejected_reason = reason if authed and not retried: retried = True self._send(['EVENT', event]) continue if self.auth_signer and not retried: # Wait for AUTH challenge if one arrives continue return accepted, reason # OK for another event (e.g. kind 22242 AUTH response); continue continue if msg[0] == 'NOTICE': return False, 'NOTICE: %s' % (msg[1] if len(msg) > 1 else '') if last_rejected_reason is not None: return False, last_rejected_reason return False, 'no OK within %.0fs' % self.timeout
[docs] def query(self, filters: Sequence[NostrFilter | Mapping[str, Any]], limit_time: Optional[float] = None) -> list[NostrEvent]: """Every stored event matching the filters, until EOSE.""" sid = self._sub_id() self._subs[sid] = list(filters) self._send(['REQ', sid] + list(filters)) out: list[NostrEvent] = [] seen: set[str] = set() deadline = time.time() + (limit_time or self.timeout) while time.time() < deadline: msg = self._recv() if msg[0] == 'AUTH' and len(msg) > 1 and isinstance(msg[1], str): self._challenged(msg[1], [sid]) continue if msg[0] == 'EVENT' and len(msg) > 2 and msg[1] == sid: ev = msg[2] # Anything that is not an object with an id is not an event and # every caller indexes ev['id'], so it is dropped here rather # than crash the first reader. if isinstance(ev, dict) and isinstance(ev.get('id'), str) and ev['id'] not in seen: seen.add(ev['id']) # The wire boundary: what a relay serves under EVENT is an # event by contract, and callers verify the ones they trust. out.append(cast(NostrEvent, ev)) elif msg[0] == 'EOSE' and len(msg) > 1 and msg[1] == sid: break elif msg[0] == 'CLOSED' and len(msg) > 1 and msg[1] == sid: reason = msg[2] if len(msg) > 2 else '' what = self._closed(sid, reason) if what in ('stale', 'retry'): continue if what == 'await': try: next_msg = self._recv() if next_msg[0] == 'AUTH' and len(next_msg) > 1 and isinstance(next_msg[1], str): if self._challenged(next_msg[1], [sid]): continue except (RelayError, ws.ConnectionClosed, OSError) as e: # The relay closed us after CLOSED without a usable AUTH # challenge; the RelayError below is the answer either way. log.debug('relay %s: no AUTH after CLOSED: %s', self.url, e) raise RelayError('relay closed the subscription: %s' % reason) self._send(['CLOSE', sid]) self._subs.pop(sid, None) self._reissued.discard(sid) return out
[docs] def subscribe(self, filters: Sequence[NostrFilter | Mapping[str, Any]], ready: bool = False) -> str: """Open a subscription; returns its id. Read with events(). `ready` waits for the relay's EOSE before returning, which is the only way a caller can know the subscription is registered. Without it this sends REQ and returns, so a caller that subscribes and then causes an event races the server: an ephemeral kind fanned out before the REQ is processed reaches nobody, is never stored, and no timeout on events() can recover it. Stored events that arrive before the EOSE are kept and handed to events() rather than dropped on the floor. """ sid = self._sub_id() self._subs[sid] = list(filters) self._send(['REQ', sid] + list(filters)) if ready and self._await_eose(sid): self._confirmed.add(sid) return sid
[docs] def confirmed(self, sid: str) -> bool: """True if the relay answered this subscription's REQ with an EOSE. Only ever true for a `subscribe(ready=True)`. A caller that waited and did not get one has a socket that is up and a subscription the relay has not owned up to, which is worth saying rather than assuming either way. """ return sid in self._confirmed
[docs] def all_confirmed(self) -> bool: """True once every open subscription on this connection has had its EOSE.""" return bool(self._subs) and all(sid in self._confirmed for sid in self._subs)
def _await_eose(self, sid: str) -> bool: """Read until this subscription's EOSE, buffering what comes first. True if the EOSE came. False if the wait ran out, the relay closed the subscription, or the socket went - the three cases where a caller that is about to cause an event must not believe it is being listened to. """ deadline = time.time() + self.timeout while time.time() < deadline: try: msg = self._recv() except socket.timeout: continue except (OSError, ws.ConnectionClosed): return False if msg[0] == 'EOSE' and len(msg) > 1 and msg[1] == sid: return True if msg[0] == 'AUTH' and len(msg) > 1 and isinstance(msg[1], str): self._challenged(msg[1], [sid]) continue if msg[0] == 'CLOSED' and len(msg) > 1 and msg[1] == sid: # 'await' keeps reading: the challenge is the next frame on a # gating relay, and the deadline is the answer on one that # closes and says nothing more. if self._closed(sid, msg[2] if len(msg) > 2 else '') == 'closed': return False continue if msg[0] == 'EVENT' and len(msg) > 2 and msg[1] == sid: self._pending.setdefault(sid, []).append(msg[2]) return False
[docs] def events(self, sid: str | Sequence[str], until: Optional[float] = None) -> Iterator[NostrEvent]: """Yield events on one subscription, or several on this connection, until `until` (a time) or the socket closes. Several, because a gating relay (strfry `restrictedReadKinds`) serves a filter that mixes a gated kind with an open one by silently dropping the gated events - no CLOSED, no AUTH, an EOSE as if nothing were missing. A caller that needs both kinds holds two subscriptions on one authenticated socket and reads them here as one stream.""" sids: tuple[str, ...] = (sid,) if isinstance(sid, str) else tuple(sid) for one in sids: for held in self._pending.pop(one, []): yield held # arrived before the EOSE `ready` waited for pinged_at: Optional[float] = None while until is None or time.time() < until: try: msg = self._recv() except socket.timeout: assert self.ws is not None idle = self.ws.idle() if idle > self.dead_after: raise ws.ConnectionClosed('no frame in %.0fs, not even a pong: the subscription is dead' % idle) if idle > self.ping_after and (pinged_at is None or time.time() - pinged_at > self.ping_after / 2): try: self.ws.ping() except OSError: return pinged_at = time.time() continue # nothing arrived; the subscription is still open except (OSError, ws.ConnectionClosed): return if msg[0] == 'AUTH' and len(msg) > 1 and isinstance(msg[1], str): self._challenged(msg[1], sids) continue if msg[0] == 'CLOSED' and len(msg) > 1 and msg[1] in sids: closed_sid = cast(str, msg[1]) what = self._closed(closed_sid, msg[2] if len(msg) > 2 else '') if what in ('stale', 'retry'): continue if what == 'await': try: next_msg = self._recv() if next_msg[0] == 'AUTH' and len(next_msg) > 1 and isinstance(next_msg[1], str): if self._challenged(next_msg[1], sids): continue except (RelayError, ws.ConnectionClosed, OSError) as e: # Same as query(): CLOSED with no AUTH to answer ends the stream. log.debug('relay %s: no AUTH after CLOSED: %s', self.url, e) return if msg[0] == 'EOSE' and len(msg) > 1 and msg[1] in sids: self._confirmed.add(cast(str, msg[1])) if self.on_eose is not None: self.on_eose(cast(str, msg[1])) continue if msg[0] == 'EVENT' and len(msg) > 2 and msg[1] in sids and isinstance(msg[2], dict): # The guard used to sit in every consumer; it belongs here, # where the promise of the return type is made. yield cast(NostrEvent, msg[2])
[docs] def unsubscribe(self, sid: str) -> None: self._send(['CLOSE', sid]) self._subs.pop(sid, None) self._reissued.discard(sid)
[docs]def publish_all( urls: Sequence[str], event: EventLike, timeout: float = 15.0, auth_signer: Optional[Callable[[str, str], Optional[EventLike]]] = None, ) -> dict[str, tuple[bool, str]]: """{url: (accepted, message)}; one failed relay does not stop the others.""" out: dict[str, tuple[bool, str]] = {} for url in urls: r = Relay(url, timeout, auth_signer=auth_signer) try: out[url] = r.publish(event) except Exception as e: out[url] = (False, '%s: %s' % (type(e).__name__, e)) finally: r.close() return out
[docs]def query_all( urls: Sequence[str], filters: Sequence[NostrFilter | Mapping[str, Any]], timeout: float = 15.0, auth_signer: Optional[Callable[[str, str], Optional[EventLike]]] = None, ) -> list[NostrEvent]: """Events from every relay, deduplicated by id.""" seen: dict[str, NostrEvent] = {} for url in urls: r = Relay(url, timeout, auth_signer=auth_signer) try: for ev in r.query(filters): seen.setdefault(ev['id'], ev) except (RelayError, ws.ConnectionClosed, OSError) as e: # One relay down must not cost the answers of the others; the # caller asked for the union of what is reachable. log.info('relay %s: query skipped: %s', url, e) finally: r.close() return list(seen.values())