lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README

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 }