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