fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/transport/bridge/compartment.py

@@ -0,0 +1,785 @@
+"""Universal Nostr Relay Bridge for fleetmesh.
+
+Bridges external standard Nostr relays (strfry, nostr-rs-relay, khatru, coracle, damus)
+with the local fleetmesh node:
+1. Ingress Engine: Connects to designated external relays over WebSocket (via Relay/ws),
+   subscribes to shard topics (#t), mesh control kinds (11801, 11803, 30803, etc.) or
+   user content kinds (0, 1, 3, 7, 1059, etc.), cryptographically verifies BIP-340 signatures,
+   enforces future timestamp and expiry limits, deduplicates, and ingests into the local
+   NodeStore with origin recorded.
+2. Egress Engine: Queues and publishes verified events (produced locally or across the mesh)
+   out to designated external relays, tracking acceptance, handling NIP-42 auth challenges,
+   and retrying on transient errors.
+3. Flow Control & Capacity: Sliding-window rate limiting per relay to protect node
+   memory and disk from upstream relay flooding, integrated with the Compartment refusal
+   and trouble reporting interfaces.
+"""
+from __future__ import annotations
+
+import json
+import threading
+import time
+from typing import Any, Callable, cast, Mapping, Optional, Sequence, Union
+from fleetmesh_core.storage import store  # noqa: E402
+from node import channels as ch_mod  # noqa: E402
+from node import compartment as compartment_mod  # noqa: E402
+from node.compartment import Command, Compartment, Need  # noqa: E402
+from node.config.parameter import Parameter  # noqa: E402
+from node import metrics as mx_mod  # noqa: E402
+from node.protocols.nostr import client as relay  # noqa: E402
+from fleetmesh_core.crypto import giftwrap  # noqa: E402
+from fleetmesh_core.wire.interfaces import NostrEvent  # noqa: E402
+from node.config import BridgeConfig  # noqa: E402
+from node.config import compartments as cfgblocks  # noqa: E402
+from node.compartment import stores as st  # noqa: E402
+from node.planes.transport.bridge.ratelimit import RateLimiter  # noqa: E402  (shared, audit D4)
+
+# The defaults live on the config block (node/config/compartments.py) so the
+# check and the compartment cannot disagree; re-exported here for callers.
+DEFAULT_INGRESS_KINDS = cfgblocks.DEFAULT_INGRESS_KINDS
+DEFAULT_EGRESS_KINDS = cfgblocks.DEFAULT_EGRESS_KINDS
+DEFAULT_INGRESS_FILTERS = cfgblocks.DEFAULT_INGRESS_FILTERS
+DEFAULT_RATE_LIMIT_PER_MIN = cfgblocks.DEFAULT_RATE_LIMIT_PER_MIN
+DEFAULT_MAX_FUTURE_SECONDS = cfgblocks.DEFAULT_MAX_FUTURE_SECONDS
+DEFAULT_MAX_EVENT_BYTES = cfgblocks.DEFAULT_MAX_EVENT_BYTES
+
+
+from .types import (
+    RelayWorkerStats,
+    BridgeStateReport,
+)
+
+class BridgeError(Exception):
+    pass
+
+
+class RelayBridgeWorker:
+    """Manages an active subscription and streaming connection to a single external Nostr relay."""
+
+    def __init__(
+        self,
+        url: str,
+        filters: Sequence[Mapping[str, Any]],
+        on_event: Callable[[NostrEvent, str], Any],
+        auth_signer: Optional[Callable[[str, str], Optional[Mapping[str, Any]]]] = None,
+        timeout: float = 15.0,
+        stop_event: Optional[threading.Event] = None,
+    ) -> None:
+        self.url: str = url
+        self.filters: list[Mapping[str, Any]] = list(filters)
+        self.on_event: Callable[[NostrEvent, str], Any] = on_event
+        self.auth_signer: Optional[Callable[[str, str], Optional[Mapping[str, Any]]]] = auth_signer
+        self.timeout: float = timeout
+
+        self.connected: bool = False
+        self.last_connected_at: Optional[int] = None
+        self.ingress_count: int = 0
+        self.egress_count: int = 0
+        self.errors_count: int = 0
+        self.last_error: Optional[str] = None
+        # Exceptions raised by on_event; the subscription outlives them.
+        self.handler_errors: int = 0
+        self.last_handler_error: Optional[str] = None
+        self.last_event_at: Optional[int] = None
+
+        self._stop_event: threading.Event = threading.Event()
+        self._bridge_stop_event: Optional[threading.Event] = stop_event
+        self._thread: Optional[threading.Thread] = None
+        self._relay: Optional[relay.Relay] = None
+        self._lock: threading.Lock = threading.Lock()
+
+    def _is_stopped(self) -> bool:
+        return self._stop_event.is_set() or (self._bridge_stop_event is not None and self._bridge_stop_event.is_set())
+
+    def start(self) -> None:
+        with self._lock:
+            if self._thread is not None and self._thread.is_alive():
+                return
+            self._stop_event.clear()
+            self._thread = threading.Thread(target=self._run, name=f'relay-bridge-{self.url}', daemon=True)
+            self._thread.start()
+
+    def stop(self) -> None:
+        self._stop_event.set()
+        with self._lock:
+            if self._relay is not None:
+                try:
+                    self._relay.close()
+                except Exception:
+                    pass
+                self._relay = None
+            self.connected = False
+        if self._thread is not None and self._thread.is_alive():
+            self._thread.join(timeout=1.0)
+            self._thread = None
+
+    def _run(self) -> None:
+        consecutive_errors = 0
+        while not self._is_stopped():
+            try:
+                r = relay.Relay(self.url, timeout=self.timeout, auth_signer=self.auth_signer)
+                r.connect()
+                with self._lock:
+                    self._relay = r
+                    self.connected = True
+                    self.last_connected_at = int(time.time())
+                    self.last_error = None
+                consecutive_errors = 0
+
+                sid = r.subscribe(self.filters, ready=False)
+                for ev in r.events(sid):
+                    if self._is_stopped():
+                        break
+                    self.ingress_count += 1
+                    self.last_event_at = int(time.time())
+                    try:
+                        self.on_event(ev, self.url)
+                    except Exception as e:
+                        # A handler bug (or one poisoned event) costs that
+                        # event, not the subscription: tearing the socket
+                        # down and reconnecting would replay the same
+                        # event and fail the same way, forever.
+                        self.handler_errors += 1
+                        self.last_handler_error = '%s: %s' % (type(e).__name__, str(e)[:200])
+
+            except Exception as e:
+                consecutive_errors += 1
+                self.errors_count += 1
+                self.last_error = f'{type(e).__name__}: {e}'
+                with self._lock:
+                    self.connected = False
+                    if self._relay is not None:
+                        try:
+                            self._relay.close()
+                        except Exception:
+                            pass
+                        self._relay = None
+            finally:
+                with self._lock:
+                    self.connected = False
+                    if self._relay is not None:
+                        try:
+                            self._relay.close()
+                        except Exception:
+                            pass
+                        self._relay = None
+
+            if not self._is_stopped():
+                backoff = min(30.0, 1.0 * (2 ** min(consecutive_errors, 5)))
+                self._stop_event.wait(backoff)
+
+    def publish(self, ev: NostrEvent) -> tuple[bool, str]:
+        """Publish one event directly to this relay, returning (accepted, reason)."""
+        pub_client = relay.Relay(self.url, timeout=self.timeout, auth_signer=self.auth_signer)
+        try:
+            pub_client.connect()
+            accepted, reason = pub_client.publish(ev)
+            if accepted:
+                self.egress_count += 1
+            return accepted, reason
+        except Exception as e:
+            self.errors_count += 1
+            self.last_error = f'publish: {type(e).__name__}: {e}'
+            return False, str(e)
+        finally:
+            pub_client.close()
+
+    def stats(self) -> RelayWorkerStats:
+        return {
+            'url': self.url,
+            'connected': self.connected,
+            'last_connected_at': self.last_connected_at,
+            'ingress_count': self.ingress_count,
+            'egress_count': self.egress_count,
+            'errors_count': self.errors_count,
+            'last_error': self.last_error,
+            'handler_errors': self.handler_errors,
+            'last_handler_error': self.last_handler_error,
+            'last_event_at': self.last_event_at,
+        }
+
+
+class RelayBridge(Compartment):
+    optional: bool = True
+    enabled_by: Optional[str] = 'bridge'
+    """The Universal Nostr Relay Bridge compartment."""
+
+    name: str = 'bridge'
+    uses: tuple[str, ...] = ('p2p',)      # external ingress is re-broadcast on the P2P gossip when it is on
+    reads: tuple[str, ...] = ('bridge', 'relays')
+    config_cls = BridgeConfig
+    live: tuple[str, ...] = ('bridge',)
+    NEEDS = (
+        Need('store_backend', 'stores.events'),
+        Need('face', 'face'),
+        Need('relays', 'relays'),
+        Need('cfg', block=BridgeConfig),
+        Need('p2p', 'p2p'),
+    )
+    STORES = (
+        st.Store(
+            key='egress_queue',
+            description='events queued for broadcast to external relays',
+            kind=st.RING,
+            bound=1000,
+        ),
+    )
+    egress_queue: st.Ring[tuple[Any, ...]]
+
+    CHANNELS = (
+        ch_mod.Channel('ingress_stored', 'An event received from an external relay was verified and stored',
+                       level=ch_mod.NOTE, say='bridge stored event {id} from {relay}',
+                       tags=('bridge', 'ingress')),
+        ch_mod.Channel('ingress_refused', 'An event received from an external relay was refused',
+                       level=ch_mod.TROUBLE, say='bridge refused event from {relay}: {reason}',
+                       tags=('bridge', 'ingress', 'refused')),
+        ch_mod.Channel('egress_sent', 'An event was published to external relays',
+                       level=ch_mod.NOTE, say='bridge published event {id} to {relay}',
+                       tags=('bridge', 'egress')),
+        ch_mod.Channel('egress_failed', 'Failed to publish event to an external relay',
+                       level=ch_mod.TROUBLE, say='bridge failed to publish to {relay}: {reason}',
+                       tags=('bridge', 'egress', 'failed')),
+    )
+    METRICS = (
+        mx_mod.Metric(name='bridge_ingress_stored', description='Events received from external relays and stored.',
+                      kind=mx_mod.COUNTER, counts='ingress_stored', tags=('bridge', 'ingress')),
+        mx_mod.Metric(name='bridge_ingress_refused', description='Events received from external relays and refused.',
+                      kind=mx_mod.COUNTER, counts='ingress_refused', tags=('bridge', 'ingress')),
+        mx_mod.Metric(name='bridge_egress_sent', description='Events published to external relays.',
+                      kind=mx_mod.COUNTER, counts='egress_sent', tags=('bridge', 'egress')),
+        mx_mod.Metric(name='bridge_egress_failed', description='Events that failed publication to external relays.',
+                      kind=mx_mod.COUNTER, counts='egress_failed', tags=('bridge', 'egress')),
+    )
+    COMMANDS = (
+        Command(
+            key='show',
+            name='Bridge Status',
+            description='display bridge status and connected relays',
+            tags=('bridge', 'status'),
+            permission='bridge/show',
+            run='state',
+            reply='dict',
+        ),
+        Command(
+            key='publish',
+            name='Publish Event',
+            description='publish a nostr event to external relays',
+            tags=('bridge', 'publish'),
+            parameters=(
+                Parameter(key='event', name='event', description='nostr event object', type=dict, default=dict, required=True),
+                Parameter(key='relays', name='relays', description='target relays list', type=list, default=None, required=False),
+            ),
+            permission='bridge/publish',
+            run='publish_cmd',
+            reply='dict',
+        ),
+        Command(
+            key='sync',
+            name='Sync Query',
+            description='query external relays for matching events',
+            tags=('bridge', 'sync'),
+            parameters=(
+                Parameter(key='filter', name='filter', description='subscription filter', type=object, default=None, required=False),
+                Parameter(key='relay', name='relay', description='target relay URL', type=str, default=None, required=False),
+            ),
+            permission='bridge/sync',
+            run='sync_cmd',
+            reply='dict',
+        ),
+        Command(
+            key='reconcile',
+            name='Reconcile With Relay',
+            description='reconcile events with a target relay',
+            tags=('bridge', 'reconcile'),
+            parameters=(
+                Parameter(key='relay', name='relay', description='target relay URL', type=str, default=None, required=False),
+                Parameter(key='filter', name='filter', description='subscription filter', type=object, default=None, required=False),
+                Parameter(key='since', name='since', description='start timestamp', type=int, default=None, required=False),
+                Parameter(key='until', name='until', description='end timestamp', type=int, default=None, required=False),
+                Parameter(key='limit', name='limit', description='max events', type=int, default=500, required=False),
+            ),
+            permission='bridge/reconcile',
+            run='reconcile_cmd',
+            reply='dict',
+        ),
+        Command(
+            key='add_relay',
+            name='Add Relay',
+            description='add an external relay URL to bridge',
+            tags=('bridge', 'relay'),
+            parameters=(
+                Parameter(key='url', name='url', description='relay ws:// or wss:// URL', type=str, default='', required=True),
+            ),
+            permission='bridge/add_relay',
+            run='add_relay_cmd',
+            reply='dict',
+        ),
+        Command(
+            key='remove_relay',
+            name='Remove Relay',
+            description='remove an external relay URL from bridge',
+            tags=('bridge', 'relay'),
+            parameters=(
+                Parameter(key='url', name='url', description='relay URL to remove', type=str, default='', required=True),
+            ),
+            permission='bridge/remove_relay',
+            run='remove_relay_cmd',
+            reply='dict',
+        ),
+        Command(
+            key='cursor',
+            name='Bridge Cursors',
+            description='query persistent relay checkpoint cursors',
+            tags=('bridge', 'cursor'),
+            permission='bridge/cursor',
+            run='cursor_cmd',
+            reply='list',
+        ),
+        Command(
+            key='cursors',
+            name='Bridge Cursors Alias',
+            description='query persistent relay checkpoint cursors (alias)',
+            tags=('bridge', 'cursor'),
+            permission='bridge/cursor',
+            run='cursor_cmd',
+            reply='list',
+        ),
+    )
+
+    TROUBLE_WINDOW: int = 1800
+
+    def __init__(
+        self,
+        store_backend: Any,
+        face: Optional[Any] = None,
+        relays: Optional[Sequence[str]] = None,
+        cfg: Optional[Union[BridgeConfig, Mapping[str, Any]]] = None,
+        clock: Optional[Callable[[], int]] = None,
+        node: Optional[Any] = None,
+        p2p: Optional[Any] = None,
+    ) -> None:
+        super().__init__(node, clock)
+        self.store: Any = store_backend
+        self.face: Optional[Any] = face
+        # The P2P compartment when the node built it (declared in `uses`,
+        # resolved once by from_context); None on a node without p2p.
+        self.p2p: Optional[Any] = p2p
+
+        # Tests hand a dict; the node hands the typed block. The block is the shape.
+        c = cfg if isinstance(cfg, BridgeConfig) else BridgeConfig.from_dict(cfg or {})
+        self.enabled: bool = c.enabled
+        self.relays: list[str] = [str(u) for u in c.relays] if c.relays is not None else list(relays or [])  # not a store: the configured relays
+
+        self.ingress_enabled: bool = c.ingress.enabled
+        self.ingress_filters: list[Mapping[str, Any]] = list(c.ingress.filters)  # not a store: ingress filters from config
+        self.rate_limit_per_min: int = c.ingress.rate_limit
+        self.future_max_seconds: int = c.ingress.max_future_seconds
+        self.max_event_bytes: int = c.ingress.max_bytes
+
+        self.egress_enabled: bool = c.egress.enabled
+        self.egress_kinds: set[int] = set(c.egress.kinds)  # not a store: egress kinds from config
+        self.auto_egress: bool = c.egress.auto
+
+        self.workers: dict[str, RelayBridgeWorker] = {}  # not a store: active worker threads per relay
+        self.rate_limiters: dict[str, RateLimiter] = {}  # not a store: rate limiters per relay
+        self._global_rate_limiter: RateLimiter = RateLimiter(self.rate_limit_per_min * max(1, len(self.relays)))
+        self._egress_queue = self.egress_queue
+        self._lock: threading.Lock = threading.Lock()
+
+        # Operational metrics
+        self.ingress_stored: int = 0
+        self.ingress_duplicates: int = 0
+        self.p2p_forward_failures: int = 0
+        self.ingress_refused: int = 0
+        self.egress_sent: int = 0
+        self.egress_failed: int = 0
+        self.last_ingress_at: Optional[int] = None
+        self.last_egress_at: Optional[int] = None
+
+        # Wire auto-egress from local face if available
+        if self.face is not None and hasattr(self.face, 'on_event_handlers'):
+            self.face.on_event_handlers.append(self._on_local_face_event)
+
+        # Initialize workers
+        for r_url in self.relays:
+            self._add_worker(r_url)
+        # The strfry relay bridge is a plugin now (fleetmesh-strfry,
+        # `fleetmesh_strfry.plugin:StrfryBridgePlugin`), not a part of this one.
+
+    def _add_worker(self, url: str) -> RelayBridgeWorker:
+        if url in self.workers:
+            return self.workers[url]
+        # No NIP-42 signer: the bridge speaks to the external relays
+        # unauthenticated. The node has no `auth_signer`, so the previous
+        # `getattr(self.node, 'auth_signer')` was always None; a bridge that
+        # authenticates is a feature, declared here when it exists.
+        worker = RelayBridgeWorker(
+            url=url,
+            filters=self.ingress_filters,
+            on_event=self.handle_ingress_event,
+            stop_event=self._stop_event,
+        )
+        self.workers[url] = worker
+        self.rate_limiters[url] = RateLimiter(self.rate_limit_per_min)
+        if self.enabled and self.ingress_enabled:
+            worker.start()
+        return worker
+
+    def _remove_worker(self, url: str) -> None:
+        worker = self.workers.pop(url, None)
+        self.rate_limiters.pop(url, None)
+        if worker is not None:
+            worker.stop()
+
+    def _on_local_face_event(self, ev: NostrEvent) -> None:
+        """Triggered whenever the local node's relay face accepts an event."""
+        if not self.enabled or not self.egress_enabled or not self.auto_egress:
+            return
+        if ev.get('kind') in self.egress_kinds:
+            self.enqueue_egress(ev)
+
+    def handle_ingress_event(self, ev: Any, relay_url: str) -> str:
+        """Ingest, validate, and store an event received from an external relay.
+
+        Returns one of: stored, duplicate, rate_limited, invalid, future_skew, expired.
+        """
+        now = self.clock()
+        eid = ev.get('id', '') if isinstance(ev, dict) else ''
+
+        # Rate limiting: relay and global
+        relay_limiter = self.rate_limiters.setdefault(relay_url, RateLimiter(self.rate_limit_per_min))
+        if not relay_limiter.allow(now) or not self._global_rate_limiter.allow(now):
+            self.ingress_refused += 1
+            self.say('ingress_refused', relay=relay_url, reason='rate limit exceeded')
+            self.refusals.refuse('ingress', 'rate limit exceeded', subject=eid[:16] or None,
+                                 detail={'relay': relay_url, 'rate_limit': self.rate_limit_per_min})
+            return 'rate_limited'
+
+        if not isinstance(ev, dict) or not isinstance(eid, str) or not eid:
+            self.ingress_refused += 1
+            self.say('ingress_refused', relay=relay_url, reason='malformed event')
+            self.refusals.refuse('ingress', 'malformed event object', subject=None,
+                                 detail={'relay': relay_url})
+            return 'invalid'
+
+        # Check payload size
+        raw_size = len(json.dumps(ev, separators=(',', ':')))
+        if raw_size > self.max_event_bytes:
+            self.ingress_refused += 1
+            self.say('ingress_refused', relay=relay_url, reason='event exceeds max size')
+            self.refusals.refuse('ingress', 'event exceeds max size', subject=eid[:16],
+                                 detail={'relay': relay_url, 'size': raw_size, 'limit': self.max_event_bytes})
+            return 'invalid'
+
+        # Check cryptographic signature & ID
+        if not giftwrap.verify_event(ev):
+            self.ingress_refused += 1
+            self.say('ingress_refused', relay=relay_url, reason='signature verification failed')
+            self.refusals.refuse('ingress', 'signature or id does not verify', subject=eid[:16],
+                                 detail={'relay': relay_url, 'pubkey': ev.get('pubkey')})
+            return 'invalid'
+
+        # Timestamp sanity check (clock skew)
+        created_at = ev.get('created_at')
+        if isinstance(created_at, int) and created_at > now + self.future_max_seconds:
+            self.ingress_refused += 1
+            self.say('ingress_refused', relay=relay_url, reason='future timestamp')
+            self.refusals.refuse('ingress', 'created_at too far in future', subject=eid[:16],
+                                 detail={'relay': relay_url, 'skew': created_at - now, 'limit': self.future_max_seconds})
+            return 'future_skew'
+
+        # Expiration check (NIP-40)
+        exp = store.expiration(ev)
+        if exp is not None and exp <= now:
+            return 'expired'
+
+        # Ephemeral check
+        if store.is_ephemeral(ev.get('kind', 0)):
+            if self.face is not None and hasattr(self.face, '_fanout'):
+                self.face._fanout(ev)
+            return 'ephemeral'
+
+        # Deduplication check
+        if hasattr(self.store, 'has_event') and self.store.has_event(eid):
+            self.ingress_duplicates += 1
+            return 'duplicate'
+
+        # Insert into store
+        result = self.store.insert_event(ev, now)
+        if result == 'stored':
+            self.ingress_stored += 1
+            self.last_ingress_at = now
+            self.say('ingress_stored', id=eid[:16], relay=relay_url)
+            if hasattr(self.store, 'note_origin'):
+                self.store.note_origin(eid, getattr(self.store, 'LOCAL', 'local'))
+            if self.face is not None and hasattr(self.face, '_fanout'):
+                self.face._fanout(ev)
+            # P2P cross-forwarding: external ingress goes out on the local
+            # gossip too. A failure there is the p2p compartment's to report;
+            # here it is counted so the bridge's own status says it happened.
+            if self.p2p is not None:
+                try:
+                    self.p2p.broadcast(ev)
+                except Exception as e:
+                    self.p2p_forward_failures += 1
+                    self.refusals.refuse('p2p forward', 'raised', subject=ev.get('id'), detail=compartment_mod.why_detail(e))
+            # Persistent checkpoint tracking
+            if hasattr(self.store, 'set_bridge_cursor') and relay_url:
+                try:
+                    self.store.set_bridge_cursor(relay_url, last_event_at=ev.get('created_at', now), count_increment=1)
+                except Exception:
+                    pass
+        elif result == 'duplicate':
+            self.ingress_duplicates += 1
+
+        return result
+
+    def publish(
+        self,
+        ev: NostrEvent,
+        target_relays: Optional[Sequence[str]] = None,
+    ) -> dict[str, tuple[bool, str]]:
+        """Publish an event to external relays.
+
+        Returns {relay_url: (accepted, reason)}.
+        """
+        targets = list(target_relays) if target_relays else list(self.workers.keys())
+        out: dict[str, tuple[bool, str]] = {}
+        for r_url in targets:
+            worker = self.workers.get(r_url)
+            if worker is None:
+                worker = self._add_worker(r_url)
+            accepted, reason = worker.publish(ev)
+            out[r_url] = (accepted, reason)
+            if accepted:
+                self.egress_sent += 1
+                self.say('egress_sent', id=ev.get('id', '')[:16], relay=r_url)
+            else:
+                self.egress_failed += 1
+                self.say('egress_failed', relay=r_url, reason=reason[:32])
+                self.refusals.refuse('egress', f'relay rejected: {reason[:32]}',
+                                     subject=ev.get('id', '')[:16],
+                                     detail={'relay': r_url, 'reason': reason})
+        if out:
+            self.last_egress_at = self.clock()
+        return out
+
+    def enqueue_egress(self, ev: NostrEvent, target_relays: Optional[Sequence[str]] = None) -> None:
+        """Enqueue an event to be published out to external relays asynchronously."""
+        with self._lock:
+            targets = list(target_relays) if target_relays else None
+            self.egress_queue.append((ev, targets))
+
+    def flush_egress(self) -> int:
+        """Process and send all queued egress events. Returns count of processed items."""
+        items: list[tuple[NostrEvent, Optional[list[str]]]] = []
+        with self._lock:
+            items = list(self.egress_queue)
+            self.egress_queue.clear()
+        for ev, targets in items:
+            self.publish(ev, targets)
+        return len(items)
+
+    def sync_query(
+        self,
+        filters: Sequence[Mapping[str, Any]],
+        target_relays: Optional[Sequence[str]] = None,
+        timeout: float = 15.0,
+    ) -> Mapping[str, Any]:
+        """Perform an ad-hoc query against external relays and ingest matching events."""
+        targets = list(target_relays) if target_relays else list(self.workers.keys())
+        results = relay.query_all(targets, filters, timeout=timeout)
+        ingested = 0
+        duplicates = 0
+        for ev in results:
+            outcome = self.handle_ingress_event(ev, 'query_sync')
+            if outcome == 'stored':
+                ingested += 1
+            elif outcome == 'duplicate':
+                duplicates += 1
+        return {
+            'queried_relays': targets,
+            'events_found': len(results),
+            'ingested': ingested,
+            'duplicates': duplicates,
+        }
+
+    def reconcile_with_relay(
+        self,
+        relay_url: str,
+        filter_spec: Optional[Mapping[str, Any]] = None,
+        since: Optional[int] = None,
+        until: Optional[int] = None,
+        limit: int = 500,
+    ) -> Mapping[str, Any]:
+        """Perform a range-bounded reconciliation against an external relay to backfill historical events."""
+        base_filter = dict(filter_spec or {})
+        if 'kinds' not in base_filter:
+            base_filter['kinds'] = list(DEFAULT_INGRESS_KINDS)
+        if since is None and hasattr(self.store, 'get_bridge_cursor'):
+            try:
+                cur = self.store.get_bridge_cursor(relay_url)
+                if cur and cur.get('last_reconciled_at'):
+                    since = cur['last_reconciled_at']
+            except Exception:
+                pass
+        if since is not None:
+            base_filter['since'] = since
+        if until is not None:
+            base_filter['until'] = until
+        base_filter['limit'] = limit
+
+        results = relay.query_all([relay_url], [base_filter], timeout=15.0)
+
+        examined = len(results)
+        stored_count = 0
+        duplicate_count = 0
+        for ev in results:
+            outcome = self.handle_ingress_event(ev, relay_url)
+            if outcome == 'stored':
+                stored_count += 1
+            elif outcome == 'duplicate':
+                duplicate_count += 1
+
+        target_until = until if until is not None else self.clock()
+        if hasattr(self.store, 'set_bridge_cursor'):
+            try:
+                self.store.set_bridge_cursor(relay_url, last_reconciled_at=target_until, count_increment=0)
+            except Exception:
+                pass
+
+        return {
+            'relay': relay_url,
+            'filter': base_filter,
+            'examined': examined,
+            'stored': stored_count,
+            'duplicates': duplicate_count,
+            'cursor': target_until,
+        }
+
+    # ---- Compartment lifecycle & control -------------------------------------------
+    def start(self) -> None:
+        super().start()
+        if not self.enabled:
+            return
+        for worker in self.workers.values():
+            if self.ingress_enabled:
+                worker.start()
+
+    def stop(self) -> list[tuple[str, str]]:
+        super().stop()
+        for worker in list(self.workers.values()):
+            worker.stop()
+        self.flush_egress()
+        return [('stopped bridge', f'{len(self.workers)} workers stopped')]
+
+    def tick(self, now: int) -> list[tuple[Any, ...]]:
+        did: list[tuple[Any, ...]] = []
+        if not self.enabled:
+            return did
+
+        # Health check on workers
+        connected_count = sum(1 for w in self.workers.values() if w.connected)
+        for url, worker in list(self.workers.items()):
+            if self.ingress_enabled and not worker.connected:
+                # Ensure thread is alive or restart
+                worker.start()
+
+        # Flush any queued egress items
+        sent_count = self.flush_egress()
+        if sent_count > 0:
+            did.append(('bridge', f'flushed {sent_count} egress events'))
+
+        did.append(('bridge', f'{connected_count}/{len(self.workers)} relays connected',
+                    f'ingress={self.ingress_stored} egress={self.egress_sent}'))
+        return did
+
+    def state(self) -> BridgeStateReport:
+        with self._lock:
+            pending_egress = len(self.egress_queue)
+        res: BridgeStateReport = {
+            'enabled': self.enabled,
+            'relays_configured': len(self.relays),
+            'relays_connected': sum(1 for w in self.workers.values() if w.connected),
+            'ingress': {
+                'enabled': self.ingress_enabled,
+                'stored': self.ingress_stored,
+                'duplicates': self.ingress_duplicates,
+                'p2p_forward_failures': self.p2p_forward_failures,
+                'refused': self.ingress_refused,
+                'last_event_at': self.last_ingress_at,
+            },
+            'egress': {
+                'enabled': self.egress_enabled,
+                'sent': self.egress_sent,
+                'failed': self.egress_failed,
+                'pending': pending_egress,
+                'last_event_at': self.last_egress_at,
+            },
+            'relays': {
+                url: w.stats() for url, w in self.workers.items()
+            },
+        }
+        return res
+
+    def trouble(self) -> list[str]:
+        out: list[str] = []
+        if not self.enabled:
+            return out
+
+        now = self.clock()
+        if self.relays and not any(w.connected for w in self.workers.values()):
+            out.append(f'all {len(self.relays)} bridge relays are disconnected')
+
+        recent_refusals = self.refusals.within(self.TROUBLE_WINDOW, now, kind='ingress')
+        if len(recent_refusals) > 20:
+            out.append(f'{len(recent_refusals)} ingress events refused in the last 30 minutes')
+
+        return out
+
+    def publish_cmd(self, args: Mapping[str, Any]) -> Any:
+        ev = args.get('event')
+        if not isinstance(ev, dict) or not isinstance(ev.get('id'), str):
+            raise BridgeError('event must be a valid nostr event object')
+        relays = args.get('relays')
+        return self.publish(cast(NostrEvent, ev), target_relays=relays)
+
+    def sync_cmd(self, args: Mapping[str, Any]) -> Any:
+        filt = args.get('filter')
+        filters = [filt] if isinstance(filt, dict) else (filt if isinstance(filt, list) else self.ingress_filters)
+        target_relay = args.get('relay')
+        targets = [str(target_relay)] if target_relay else None
+        return self.sync_query(filters, target_relays=targets)
+
+    def reconcile_cmd(self, args: Mapping[str, Any]) -> Any:
+        url = args.get('relay') or (self.relays[0] if self.relays else None)
+        if not url:
+            raise BridgeError('no target relay specified for reconcile')
+        filter_spec = args.get('filter')
+        since = args.get('since')
+        until = args.get('until')
+        limit = args.get('limit') or 500
+        return self.reconcile_with_relay(str(url), filter_spec=filter_spec, since=since, until=until, limit=int(limit))
+
+    def add_relay_cmd(self, args: Mapping[str, Any]) -> Mapping[str, Any]:
+        url = args.get('url')
+        if not isinstance(url, str) or not url.startswith(('ws://', 'wss://')):
+            raise BridgeError('url must be a ws:// or wss:// URL')
+        if url not in self.relays:
+            self.relays.append(url)
+        worker = self._add_worker(url)
+        return {'added': url, 'connected': worker.connected}
+
+    def remove_relay_cmd(self, args: Mapping[str, Any]) -> Mapping[str, Any]:
+        url = args.get('url')
+        if not isinstance(url, str):
+            raise BridgeError('url must be a string')
+        if url in self.relays:
+            self.relays.remove(url)
+        self._remove_worker(url)
+        return {'removed': url}
+
+    def cursor_cmd(self) -> Any:
+        if hasattr(self.store, 'all_bridge_cursors'):
+            return self.store.all_bridge_cursors()
+        return []