client.rs (20706B)
1 //! Concrete Nostr transport composition. 2 3 use crate::{Error, RelayEndpoint, RelayProfile, RelayProfileKind, RelayStatusReport, RelayUrl}; 4 use core::fmt; 5 use std::sync::{ 6 Arc, 7 atomic::{AtomicU64, Ordering}, 8 }; 9 10 /// Maximum relay targets accepted by one transport instance. 11 pub(crate) const MAX_RELAYS: usize = 64; 12 const MAX_TIMEOUT_MS: u64 = 120_000; 13 const MAX_CONNECTIONS: usize = 64; 14 const MAX_RECONNECT_DELAY_MS: u64 = 15 * 60 * 1_000; 15 16 /// Deterministic exponential reconnect policy applied independently per relay 17 /// and capability direction. 18 #[derive(Clone, Copy, Debug, Eq, PartialEq)] 19 pub struct ReconnectBackoff { 20 initial_delay_ms: u64, 21 max_delay_ms: u64, 22 } 23 24 impl ReconnectBackoff { 25 /// Creates a bounded reconnect policy. 26 pub fn new(initial_delay_ms: u64, max_delay_ms: u64) -> Result<Self, Error> { 27 if initial_delay_ms == 0 28 || max_delay_ms < initial_delay_ms 29 || max_delay_ms > MAX_RECONNECT_DELAY_MS 30 { 31 return Err(Error::InvalidReconnectBackoff { 32 initial_delay_ms, 33 max_delay_ms, 34 }); 35 } 36 Ok(Self { 37 initial_delay_ms, 38 max_delay_ms, 39 }) 40 } 41 42 /// Returns the first delay after a retryable failure. 43 #[must_use] 44 pub const fn initial_delay_ms(self) -> u64 { 45 self.initial_delay_ms 46 } 47 48 /// Returns the upper bound for any computed reconnect delay. 49 #[must_use] 50 pub const fn max_delay_ms(self) -> u64 { 51 self.max_delay_ms 52 } 53 54 pub(crate) fn delay_ms(self, consecutive_failures: u32) -> u64 { 55 let exponent = consecutive_failures.saturating_sub(1).min(63); 56 self.initial_delay_ms 57 .saturating_mul(1_u64 << exponent) 58 .min(self.max_delay_ms) 59 } 60 } 61 62 impl Default for ReconnectBackoff { 63 fn default() -> Self { 64 Self { 65 initial_delay_ms: 1_000, 66 max_delay_ms: 60_000, 67 } 68 } 69 } 70 71 /// Validated configuration for a concrete Nostr transport. 72 #[derive(Clone, Debug, Eq, PartialEq)] 73 pub struct Config { 74 profile_kind: RelayProfileKind, 75 endpoints: Vec<RelayEndpoint>, 76 relays: Vec<RelayUrl>, 77 connect_timeout_ms: u64, 78 request_timeout_ms: u64, 79 status_timeout_ms: u64, 80 max_connections: usize, 81 reconnect_backoff: ReconnectBackoff, 82 } 83 84 impl Config { 85 /// Builds inert transport configuration from one validated host profile. 86 #[must_use] 87 pub fn from_profile(profile: RelayProfile) -> Self { 88 let relays: Vec<_> = profile 89 .endpoints() 90 .iter() 91 .map(|endpoint| endpoint.url().clone()) 92 .collect(); 93 let max_connections = 8.min(relays.len()); 94 Self { 95 profile_kind: profile.kind(), 96 endpoints: profile.endpoints().to_vec(), 97 relays, 98 connect_timeout_ms: 10_000, 99 request_timeout_ms: 30_000, 100 status_timeout_ms: 5_000, 101 max_connections, 102 reconnect_backoff: ReconnectBackoff::default(), 103 } 104 } 105 106 /// Sets explicit bounded connection, request, and status timeouts. 107 pub fn with_timeouts( 108 mut self, 109 connect_timeout_ms: u64, 110 request_timeout_ms: u64, 111 status_timeout_ms: u64, 112 ) -> Result<Self, Error> { 113 validate_timeout("connect", connect_timeout_ms)?; 114 validate_timeout("request", request_timeout_ms)?; 115 validate_timeout("status", status_timeout_ms)?; 116 self.connect_timeout_ms = connect_timeout_ms; 117 self.request_timeout_ms = request_timeout_ms; 118 self.status_timeout_ms = status_timeout_ms; 119 Ok(self) 120 } 121 122 /// Sets the maximum simultaneous relay connections for one operation. 123 pub fn with_max_connections(mut self, value: usize) -> Result<Self, Error> { 124 if value == 0 || value > MAX_CONNECTIONS || value > self.relays.len() { 125 return Err(Error::InvalidConnectionLimit { value }); 126 } 127 self.max_connections = value; 128 Ok(self) 129 } 130 131 /// Sets the deterministic per-relay reconnect policy. 132 #[must_use] 133 pub const fn with_reconnect_backoff(mut self, value: ReconnectBackoff) -> Self { 134 self.reconnect_backoff = value; 135 self 136 } 137 138 /// Returns the selected host profile kind. 139 #[must_use] 140 pub const fn profile_kind(&self) -> RelayProfileKind { 141 self.profile_kind 142 } 143 144 /// Returns configured endpoints with directional access and network policy. 145 #[must_use] 146 pub fn endpoints(&self) -> &[RelayEndpoint] { 147 self.endpoints.as_slice() 148 } 149 150 /// Returns relays in caller-specified order. 151 pub fn relays(&self) -> &[RelayUrl] { 152 self.relays.as_slice() 153 } 154 155 /// Returns relays authorized for reads in deterministic profile order. 156 pub fn read_relays(&self) -> impl Iterator<Item = &RelayUrl> { 157 self.endpoints 158 .iter() 159 .filter_map(|endpoint| endpoint.access().can_read().then_some(endpoint.url())) 160 } 161 162 /// Returns relays authorized for publication in deterministic profile order. 163 pub fn write_relays(&self) -> impl Iterator<Item = &RelayUrl> { 164 self.endpoints 165 .iter() 166 .filter_map(|endpoint| endpoint.access().can_write().then_some(endpoint.url())) 167 } 168 169 pub(crate) fn endpoint_for_target( 170 &self, 171 target: &radroots_transport::Target, 172 ) -> Option<&RelayEndpoint> { 173 (*target.kind() == radroots_transport::TransportId::NOSTR) 174 .then(|| target.uri().as_str()) 175 .and_then(|url| { 176 self.endpoints 177 .iter() 178 .find(|endpoint| endpoint.url().as_str() == url) 179 }) 180 } 181 182 /// Returns the connection establishment deadline in milliseconds. 183 pub const fn connect_timeout_ms(&self) -> u64 { 184 self.connect_timeout_ms 185 } 186 187 /// Returns the bounded request deadline in milliseconds. 188 pub const fn request_timeout_ms(&self) -> u64 { 189 self.request_timeout_ms 190 } 191 192 /// Returns the passive status observation deadline in milliseconds. 193 pub const fn status_timeout_ms(&self) -> u64 { 194 self.status_timeout_ms 195 } 196 197 /// Returns the maximum simultaneous relay connections. 198 pub const fn max_connections(&self) -> usize { 199 self.max_connections 200 } 201 202 /// Returns the per-relay reconnect policy. 203 #[must_use] 204 pub const fn reconnect_backoff(&self) -> ReconnectBackoff { 205 self.reconnect_backoff 206 } 207 } 208 209 fn validate_timeout(field: &'static str, value_ms: u64) -> Result<(), Error> { 210 if value_ms == 0 || value_ms > MAX_TIMEOUT_MS { 211 return Err(Error::InvalidTimeout { field, value_ms }); 212 } 213 Ok(()) 214 } 215 216 pub(crate) async fn connect_relay( 217 client: &nostr_sdk::client::Client, 218 url: &str, 219 timeout: std::time::Duration, 220 ) -> Result<nostr_sdk::relay::Relay, nostr_sdk::error::Error> { 221 let relay = client.relay(url).await?.ok_or_else(|| { 222 nostr_sdk::error::Error::with_static_message( 223 nostr_sdk::error::ErrorKind::NotFound, 224 "configured relay is unavailable", 225 ) 226 })?; 227 relay.try_connect().timeout(timeout).await?; 228 Ok(relay) 229 } 230 231 pub(crate) async fn connect_tracked( 232 client: &nostr_sdk::client::Client, 233 connections: &crate::connections::Connections, 234 url: &str, 235 timeout: std::time::Duration, 236 ) -> Result<nostr_sdk::relay::Relay, nostr_sdk::error::Error> { 237 let relay = client.relay(url).await?.ok_or_else(|| { 238 nostr_sdk::error::Error::with_static_message( 239 nostr_sdk::error::ErrorKind::NotFound, 240 "configured relay is unavailable", 241 ) 242 })?; 243 connections.register(relay)?; 244 connect_relay(client, url, timeout).await 245 } 246 247 #[derive(Debug)] 248 struct VerifiedEventAdmission; 249 250 impl nostr_sdk::policy::AdmitPolicy for VerifiedEventAdmission { 251 fn admit_event<'a>( 252 &'a self, 253 _relay_url: &'a nostr_sdk::prelude::RelayUrl, 254 _subscription_id: &'a nostr_sdk::prelude::SubscriptionId, 255 event: &'a nostr_sdk::prelude::Event, 256 ) -> futures::future::BoxFuture< 257 'a, 258 Result<nostr_sdk::policy::AdmitStatus, nostr_sdk::error::Error>, 259 > { 260 Box::pin(async move { 261 // The SDK verification cache keys only the ID, not the received body or signature. 262 Ok(if event.verify().is_ok() { 263 nostr_sdk::policy::AdmitStatus::Success 264 } else { 265 nostr_sdk::policy::AdmitStatus::Rejected { reason: None } 266 }) 267 }) 268 } 269 } 270 271 /// Concrete Nostr implementation of the transport source and sink SPIs. 272 #[derive(Clone)] 273 pub struct NostrTransport { 274 config: Config, 275 session_client: nostr_sdk::client::Client, 276 pub(crate) connections: Arc<crate::connections::Connections>, 277 pub(crate) client: Arc<dyn crate::sink::RelayClient>, 278 pub(crate) source_client: Arc<dyn crate::source::RelaySourceClient>, 279 pub(crate) subscription_client: Arc<dyn crate::subscription::RelaySubscriptionClient>, 280 pub(crate) auth: Arc<crate::auth::AuthFlow>, 281 pub(crate) status: Arc<crate::status::StatusTracker>, 282 subscription_sequence: Arc<AtomicU64>, 283 } 284 285 impl NostrTransport { 286 /// Creates an inert transport from validated explicit configuration. 287 pub fn new( 288 config: Config, 289 host: Arc<dyn radroots_transport::host::websocket::Connector>, 290 ) -> Self { 291 let connector = crate::session_socket::SessionWebsocketTransport::new( 292 config.endpoints(), 293 std::time::Duration::from_millis(config.connect_timeout_ms()), 294 host, 295 ); 296 let writers = connector.writers.clone(); 297 let ingress = connector.ingress.clone(); 298 let client = nostr_sdk::client::Client::builder() 299 .websocket_transport(connector) 300 .admit_policy(VerifiedEventAdmission) 301 .max_relays(std::num::NonZeroUsize::new(config.endpoints().len())) 302 .connect_timeout(std::time::Duration::from_millis( 303 config.connect_timeout_ms(), 304 )) 305 .build(); 306 let status = Arc::new(crate::status::StatusTracker::new(&config)); 307 let connections = Arc::new(crate::connections::Connections::new( 308 config.endpoints().len(), 309 )); 310 Self { 311 config, 312 session_client: client.clone(), 313 connections: Arc::clone(&connections), 314 client: Arc::new(crate::sink::LiveRelayClient::new( 315 client.clone(), 316 writers, 317 Arc::clone(&connections), 318 )), 319 source_client: Arc::new(crate::source::LiveRelaySourceClient::new( 320 client.clone(), 321 ingress.clone(), 322 Arc::clone(&connections), 323 )), 324 subscription_client: Arc::new(crate::subscription::LiveRelaySubscriptionClient::new( 325 client.clone(), 326 connections, 327 ingress, 328 )), 329 auth: Arc::new(crate::auth::AuthFlow::new(Arc::new( 330 crate::auth::LiveAuthClient::new(client), 331 ))), 332 status, 333 subscription_sequence: Arc::new(AtomicU64::new(0)), 334 } 335 } 336 337 /// Returns the transport configuration. 338 pub const fn config(&self) -> &Config { 339 &self.config 340 } 341 342 /// Returns passive per-relay and aggregate evidence without network I/O. 343 #[must_use] 344 pub fn relay_status(&self) -> RelayStatusReport { 345 self.status.report() 346 } 347 348 /// Closes admission, disposes pending AUTH challenges and shuts down the owned relay pool. 349 /// 350 /// An unpolled future has no effect. Re-await after cancellation to finish 351 /// cleanup. This is idempotent across clones; already-started operations 352 /// must still be awaited and their obtained results retained by their owner. 353 /// Upstream pool shutdown signals its relay tasks; this method does not 354 /// claim to join every upstream internal task. 355 pub async fn shutdown(&self) { 356 self.close_admission(); 357 self.session_client.shutdown().await; 358 } 359 360 /// Refuses new calls while already-started calls retain their exact observations. 361 /// 362 /// When the last active call completes or is cancelled, its registered 363 /// relays disconnect synchronously. The owner must still await pool 364 /// shutdown; this method claims neither task joining nor durable completion. 365 pub fn close_admission(&self) { 366 self.connections.close(); 367 self.auth.close(); 368 } 369 370 /// Reports active transport calls, excluding passive status and live subscription handles. 371 pub fn has_in_flight_operations(&self) -> bool { 372 self.connections.has_active_calls() 373 } 374 375 /// Reports closed admission, including interrupted shutdown, without claiming task joining. 376 pub fn admission_is_closed(&self) -> bool { 377 self.connections.is_closed() 378 } 379 380 pub(crate) fn require_open(&self) -> Result<(), radroots_transport::Error> { 381 if self.admission_is_closed() { 382 Err(radroots_transport::Error::TransportClosed) 383 } else { 384 Ok(()) 385 } 386 } 387 388 #[cfg(test)] 389 pub(crate) fn with_client(config: Config, client: Arc<dyn crate::sink::RelayClient>) -> Self { 390 let status = Arc::new(crate::status::StatusTracker::new(&config)); 391 Self { 392 config, 393 session_client: nostr_sdk::client::Client::default(), 394 connections: Arc::new(crate::connections::Connections::new(MAX_RELAYS)), 395 client, 396 source_client: Arc::new(crate::source::LiveRelaySourceClient::isolated()), 397 subscription_client: Arc::new( 398 crate::subscription::LiveRelaySubscriptionClient::isolated(), 399 ), 400 auth: Arc::new(crate::auth::AuthFlow::isolated()), 401 status, 402 subscription_sequence: Arc::new(AtomicU64::new(0)), 403 } 404 } 405 406 #[cfg(test)] 407 pub(crate) fn with_source_client( 408 config: Config, 409 source_client: Arc<dyn crate::source::RelaySourceClient>, 410 ) -> Self { 411 let status = Arc::new(crate::status::StatusTracker::new(&config)); 412 Self { 413 config, 414 session_client: nostr_sdk::client::Client::default(), 415 connections: Arc::new(crate::connections::Connections::new(MAX_RELAYS)), 416 client: Arc::new(crate::sink::LiveRelayClient::isolated()), 417 source_client, 418 subscription_client: Arc::new( 419 crate::subscription::LiveRelaySubscriptionClient::isolated(), 420 ), 421 auth: Arc::new(crate::auth::AuthFlow::isolated()), 422 status, 423 subscription_sequence: Arc::new(AtomicU64::new(0)), 424 } 425 } 426 427 #[cfg(test)] 428 pub(crate) fn with_subscription_client( 429 config: Config, 430 subscription_client: Arc<dyn crate::subscription::RelaySubscriptionClient>, 431 ) -> Self { 432 let status = Arc::new(crate::status::StatusTracker::new(&config)); 433 Self { 434 config, 435 session_client: nostr_sdk::client::Client::default(), 436 connections: Arc::new(crate::connections::Connections::new(MAX_RELAYS)), 437 client: Arc::new(crate::sink::LiveRelayClient::isolated()), 438 source_client: Arc::new(crate::source::LiveRelaySourceClient::isolated()), 439 subscription_client, 440 auth: Arc::new(crate::auth::AuthFlow::isolated()), 441 status, 442 subscription_sequence: Arc::new(AtomicU64::new(0)), 443 } 444 } 445 446 pub(crate) fn next_subscription_sequence(&self) -> Result<u64, radroots_transport::Error> { 447 self.subscription_sequence 448 .try_update(Ordering::SeqCst, Ordering::SeqCst, |current| { 449 current.checked_add(1) 450 }) 451 .map(|previous| previous + 1) 452 .map_err(|_| radroots_transport::Error::SubscriptionUnavailable) 453 } 454 } 455 456 impl fmt::Debug for NostrTransport { 457 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { 458 formatter 459 .debug_struct("NostrTransport") 460 .field("config", &self.config) 461 .finish_non_exhaustive() 462 } 463 } 464 465 #[cfg(test)] 466 #[path = "native_backend_tests.rs"] 467 mod native_backend_tests; 468 469 #[cfg(test)] 470 mod tests { 471 use super::*; 472 473 #[test] 474 fn config_rejects_empty_duplicate_and_excessive_relay_sets() { 475 assert!( 476 crate::profile::test_profile( 477 RelayProfileKind::Simulator, 478 crate::RelayUrlPolicy::Local, 479 Vec::<String>::new(), 480 ) 481 .is_err() 482 ); 483 assert!( 484 crate::profile::test_profile( 485 RelayProfileKind::Public, 486 crate::RelayUrlPolicy::Public, 487 ["wss://relay.example.com", "wss://RELAY.EXAMPLE.COM:443/"], 488 ) 489 .is_err() 490 ); 491 let relays = (0..=MAX_RELAYS).map(|index| format!("wss://r{index}.example.com")); 492 assert!( 493 crate::profile::test_profile( 494 RelayProfileKind::Public, 495 crate::RelayUrlPolicy::Public, 496 relays, 497 ) 498 .is_err() 499 ); 500 } 501 502 #[test] 503 fn config_rejects_unbounded_limits() { 504 let config = Config::from_profile( 505 crate::profile::test_profile( 506 RelayProfileKind::Public, 507 crate::RelayUrlPolicy::Public, 508 ["wss://relay.example.com"], 509 ) 510 .expect("profile"), 511 ); 512 assert!(config.clone().with_timeouts(0, 1, 1).is_err()); 513 assert!(config.clone().with_timeouts(1, 120_001, 1).is_err()); 514 assert!(config.with_max_connections(3).is_err()); 515 } 516 517 #[test] 518 fn valid_configuration_accessors_and_transport_debug_are_complete() { 519 let config = Config::from_profile( 520 crate::profile::test_profile( 521 RelayProfileKind::Public, 522 crate::RelayUrlPolicy::Public, 523 ["wss://one.example", "wss://two.example"], 524 ) 525 .expect("profile"), 526 ) 527 .with_timeouts(1, 2, 3) 528 .expect("timeouts") 529 .with_max_connections(2) 530 .expect("connections"); 531 assert_eq!(config.relays().len(), 2); 532 assert_eq!(config.read_relays().count(), 2); 533 assert_eq!(config.write_relays().count(), 2); 534 assert_eq!(config.profile_kind(), RelayProfileKind::Public); 535 assert_eq!(config.connect_timeout_ms(), 1); 536 assert_eq!(config.request_timeout_ms(), 2); 537 assert_eq!(config.status_timeout_ms(), 3); 538 assert_eq!(config.max_connections(), 2); 539 assert_eq!(config.reconnect_backoff(), ReconnectBackoff::default()); 540 assert!(ReconnectBackoff::new(0, 1).is_err()); 541 assert!(ReconnectBackoff::new(2, 1).is_err()); 542 assert!(ReconnectBackoff::new(1, MAX_RECONNECT_DELAY_MS + 1).is_err()); 543 let backoff = ReconnectBackoff::new(2, 5).expect("backoff"); 544 assert_eq!(backoff.delay_ms(0), 2); 545 assert_eq!(backoff.delay_ms(1), 2); 546 assert_eq!(backoff.delay_ms(2), 4); 547 assert_eq!(backoff.delay_ms(3), 5); 548 assert!(config.clone().with_timeouts(120_001, 1, 1).is_err()); 549 assert!(config.clone().with_timeouts(1, 1, 0).is_err()); 550 assert!(config.clone().with_max_connections(0).is_err()); 551 assert!( 552 config 553 .clone() 554 .with_max_connections(MAX_CONNECTIONS + 1) 555 .is_err() 556 ); 557 558 let transport = crate::test_host::transport(config.clone()); 559 assert_eq!(transport.config(), &config); 560 let debug = format!("{transport:?}"); 561 assert!(debug.contains("NostrTransport")); 562 assert!(!debug.contains("client")); 563 } 564 565 #[test] 566 fn subscription_sequence_is_monotonic_and_fails_closed_at_overflow() { 567 let config = Config::from_profile( 568 crate::profile::test_profile( 569 RelayProfileKind::Public, 570 crate::RelayUrlPolicy::Public, 571 ["wss://relay.example.com"], 572 ) 573 .expect("profile"), 574 ); 575 let transport = crate::test_host::transport(config); 576 assert_eq!(transport.next_subscription_sequence(), Ok(1)); 577 assert_eq!(transport.next_subscription_sequence(), Ok(2)); 578 transport 579 .subscription_sequence 580 .store(u64::MAX, Ordering::SeqCst); 581 assert_eq!( 582 transport.next_subscription_sequence(), 583 Err(radroots_transport::Error::SubscriptionUnavailable) 584 ); 585 } 586 }