From a56e12e0aed87c68fd49b453b5c3dc0bfbf81285 Mon Sep 17 00:00:00 2001 From: DanConwayDev Date: Thu, 11 Dec 2025 13:00:34 +0000 Subject: docs(sync): document why RelayConnection uses Client instead of Relay directly nostr-sdk 0.44's Relay::new() is pub(crate), making it impossible to construct a Relay directly from outside the crate. Relays can only be created through Client::add_relay() or RelayPool::add_relay(). This commit: - Adds 'Why Client instead of Relay directly?' section to struct docs - Updates run_event_loop() docs to explain the API constraint - Removes outdated 'Future Refactoring' suggestion (not feasible) --- src/sync/relay_connection.rs | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) (limited to 'src/sync') diff --git a/src/sync/relay_connection.rs b/src/sync/relay_connection.rs index 91825f2..32071e5 100644 --- a/src/sync/relay_connection.rs +++ b/src/sync/relay_connection.rs @@ -32,6 +32,17 @@ pub enum RelayEvent { /// - Layer 1 subscription (announcements) /// - Additional filter subscriptions (Layers 2 & 3) /// - Event notification loop +/// +/// # Why Client instead of Relay directly? +/// +/// While it would be cleaner to hold a `Relay` directly (since we only manage +/// one relay per connection), the nostr-sdk API makes `Relay::new()` private +/// (`pub(crate)`). Relays can only be created through `Client::add_relay()` or +/// `RelayPool::add_relay()`. This is an intentional design in nostr-sdk to +/// ensure proper lifecycle management. +/// +/// The Client adds minimal overhead since we configure it with a single relay, +/// and we retrieve the `Relay` reference for notification handling. #[derive(Clone)] pub struct RelayConnection { /// The relay URL this connection is for @@ -135,10 +146,8 @@ impl RelayConnection { /// `RelayNotification::RelayStatus` events are not forwarded to the pool-level channel. /// This enables immediate, event-driven disconnect detection without polling. /// - /// # Future Refactoring - /// Consider refactoring `RelayConnection` to hold a `Relay` directly instead of - /// wrapping a `Client`. This would simplify the architecture since we only manage - /// one relay per connection. + /// We must retrieve the Relay from the Client because nostr-sdk does not expose + /// `Relay::new()` publicly - relays can only be created through Client or RelayPool. pub async fn run_event_loop(self, event_sender: mpsc::Sender) { let url = self.url.clone(); @@ -324,4 +333,4 @@ impl RelayConnection { self.client.unsubscribe_all().await; tracing::debug!(relay = %self.url, "Unsubscribed from all subscriptions"); } -} \ No newline at end of file +} -- cgit v1.2.3