Skip to main content

rostra_client/
client.rs

1use std::collections::{BTreeSet, HashMap};
2use std::future::Future;
3use std::marker::PhantomData;
4use std::net::Ipv4Addr;
5use std::ops;
6use std::option::Option;
7use std::path::Path;
8use std::str::FromStr as _;
9use std::sync::atomic::AtomicBool;
10use std::sync::atomic::Ordering::SeqCst;
11use std::sync::{Arc, Mutex, Weak};
12use std::time::Duration;
13
14use backon::Retryable as _;
15use iroh_base::EndpointAddr;
16use n0_future::task::AbortOnDropHandle;
17use rostra_client_db::{
18    CurrentState, Database, DbError, DbResult, IdsFolloweesRecord, IdsFollowersRecord, WotData,
19};
20use rostra_core::event::{
21    Event, EventContentRaw, EventExt as _, IrohNodeId, PersonaTag, PersonasTagsSelector,
22    SignedEvent, SocialPost, VerifiedEvent, VerifiedEventContent, content_kind,
23};
24use rostra_core::id::{RostraId, RostraIdSecretKey};
25use rostra_core::{ExternalEventId, ShortEventId, Timestamp};
26use rostra_p2p::RpcError;
27use rostra_p2p::connection::{Connection, FeedEventResponse};
28use rostra_p2p_api::ROSTRA_P2P_V0_ALPN;
29use rostra_util_error::{FmtCompact as _, WhateverResult};
30use snafu::{Location, OptionExt as _, ResultExt as _, Snafu, ensure};
31use tokio::sync::{RwLock, broadcast};
32use tokio::time::Instant;
33use tracing::{debug, info, trace, warn};
34
35use crate::LOG_TARGET;
36use crate::error::{
37    ActivateResult, ActivateSnafu, ConnectResult, IdResolveError, IdResolveResult,
38    IdSecretReadResult, InitIrohClientSnafu, InitPkarrClientSnafu, InitResult, IoSnafu,
39    LocalAnnouncementStorageSnafu, ParsingSnafu, PostResult, SecretMismatchSnafu, StorageSnafu,
40    StoreEventError, StoreEventResult,
41};
42use crate::id::{CompactTicket, IdResolvedData};
43use crate::task::head_merger::HeadMerger;
44use crate::task::missing_event_content_fetcher::MissingEventContentFetcher;
45use crate::task::missing_event_fetcher::MissingEventFetcher;
46use crate::task::pkarr_id_publisher::PkarrIdPublisher;
47use crate::task::request_handler::RequestHandler;
48
49/// Per-identity P2P connection state for debugging.
50///
51/// Tracks connection attempts, successes, failures, and head check results.
52/// This is in-memory only and populates over time as connections are made.
53#[derive(Debug, Clone, Default)]
54pub struct IdP2PState {
55    /// Last time we attempted to connect to this ID
56    pub last_attempt: Option<Timestamp>,
57    /// Last successful connection time
58    pub last_success: Option<Timestamp>,
59    /// Last failed connection time
60    pub last_failure: Option<Timestamp>,
61    /// Last head resolved from pkarr TXT record
62    pub last_pkarr_head: Option<ShortEventId>,
63    /// Timestamp of last pkarr resolution
64    pub last_pkarr_resolve: Option<Timestamp>,
65    /// Last head obtained from iroh connection
66    pub last_checked_head: Option<ShortEventId>,
67    /// Timestamp of last head check via iroh
68    pub last_head_check: Option<Timestamp>,
69}
70
71/// Per-node (Iroh endpoint) connection state for debugging.
72///
73/// Tracks connection attempts, successes, and failures per node.
74#[derive(Debug, Clone, Default)]
75pub struct NodeP2PState {
76    /// Last time we attempted to connect to this node
77    pub last_attempt: Option<Timestamp>,
78    /// Last successful connection time
79    pub last_success: Option<Timestamp>,
80    /// Last failed connection time
81    pub last_failure: Option<Timestamp>,
82    /// Source of how we learned about this node
83    pub source: NodeSource,
84    /// The RostraId this node is associated with (if known)
85    pub rostra_id: Option<RostraId>,
86    /// Number of consecutive connection failures
87    pub consecutive_failures: u32,
88    /// Time until which we should not attempt to connect (backoff)
89    pub backoff_until: Option<Instant>,
90}
91
92/// Maximum backoff duration for failed connection attempts (10 minutes)
93pub const MAX_BACKOFF_DURATION: Duration = Duration::from_secs(10 * 60);
94
95/// Initial backoff duration for failed connection attempts (1 second)
96pub const INITIAL_BACKOFF_DURATION: Duration = Duration::from_secs(1);
97
98impl NodeP2PState {
99    /// Calculate the backoff duration based on consecutive failures.
100    ///
101    /// Uses exponential backoff: 1s, 2s, 4s, 8s, ... capped at 10 minutes.
102    pub(crate) fn calculate_backoff_duration(&self) -> Duration {
103        if self.consecutive_failures == 0 {
104            return Duration::ZERO;
105        }
106        let shift = self.consecutive_failures.saturating_sub(1).min(63);
107        let multiplier = 1u64 << shift;
108        let backoff_secs = INITIAL_BACKOFF_DURATION
109            .as_secs()
110            .saturating_mul(multiplier);
111        Duration::from_secs(backoff_secs).min(MAX_BACKOFF_DURATION)
112    }
113
114    /// Check if we should skip connecting due to backoff.
115    pub fn is_in_backoff(&self) -> bool {
116        self.backoff_until
117            .map(|until| Instant::now() < until)
118            .unwrap_or(false)
119    }
120
121    /// Record a successful connection, resetting backoff state.
122    pub(crate) fn record_success(&mut self, now: Timestamp) {
123        self.last_success = Some(now);
124        self.consecutive_failures = 0;
125        self.backoff_until = None;
126    }
127
128    /// Record a failed connection, updating backoff state.
129    pub(crate) fn record_failure(&mut self, now: Timestamp) {
130        self.last_failure = Some(now);
131        self.consecutive_failures = self.consecutive_failures.saturating_add(1);
132        let backoff_duration = self.calculate_backoff_duration();
133        self.backoff_until = Some(Instant::now() + backoff_duration);
134    }
135}
136
137/// How we learned about a node.
138#[derive(Debug, Clone, Default, PartialEq, Eq)]
139pub enum NodeSource {
140    /// From a NodeAnnouncement event stored in the database
141    #[default]
142    NodeAnnouncement,
143    /// From pkarr DNS resolution
144    Pkarr,
145}
146
147/// In-memory P2P state for all known identities.
148///
149/// Used by the P2P Explorer UI to display connection and resolution status.
150#[derive(Debug, Default)]
151pub struct P2PState {
152    ids: RwLock<HashMap<RostraId, IdP2PState>>,
153    nodes: RwLock<HashMap<IrohNodeId, NodeP2PState>>,
154}
155
156const P2P_IDS_WARN_LIMIT: usize = 10_000;
157const P2P_NODES_WARN_LIMIT: usize = 10_000;
158
159impl P2PState {
160    pub(crate) fn new() -> Self {
161        Self::default()
162    }
163
164    /// Get the P2P state for a specific identity.
165    pub async fn get(&self, id: RostraId) -> IdP2PState {
166        self.ids.read().await.get(&id).cloned().unwrap_or_default()
167    }
168
169    /// Get P2P state for all known identities.
170    pub async fn get_all(&self) -> HashMap<RostraId, IdP2PState> {
171        self.ids.read().await.clone()
172    }
173
174    /// Update the P2P state for an identity.
175    pub(crate) async fn update(&self, id: RostraId, f: impl FnOnce(&mut IdP2PState)) {
176        let mut ids = self.ids.write().await;
177        let state = ids.entry(id).or_default();
178        f(state);
179        if ids.len() == P2P_IDS_WARN_LIMIT + 1 {
180            warn!(
181                target: LOG_TARGET,
182                len = ids.len(),
183                limit = P2P_IDS_WARN_LIMIT,
184                "P2P identity state map is large"
185            );
186        }
187    }
188
189    /// Get the P2P state for a specific node.
190    pub async fn get_node(&self, node_id: IrohNodeId) -> NodeP2PState {
191        self.nodes
192            .read()
193            .await
194            .get(&node_id)
195            .cloned()
196            .unwrap_or_default()
197    }
198
199    /// Get P2P state for all known nodes.
200    pub async fn get_all_nodes(&self) -> HashMap<IrohNodeId, NodeP2PState> {
201        self.nodes.read().await.clone()
202    }
203
204    /// Update the P2P state for a node.
205    pub(crate) async fn update_node(&self, node_id: IrohNodeId, f: impl FnOnce(&mut NodeP2PState)) {
206        let mut nodes = self.nodes.write().await;
207        let state = nodes.entry(node_id).or_default();
208        f(state);
209        if nodes.len() == P2P_NODES_WARN_LIMIT + 1 {
210            warn!(
211                target: LOG_TARGET,
212                len = nodes.len(),
213                limit = P2P_NODES_WARN_LIMIT,
214                "P2P node state map is large"
215            );
216        }
217    }
218
219    /// Check if a node is currently in backoff.
220    pub async fn is_node_in_backoff(&self, node_id: IrohNodeId) -> bool {
221        self.nodes
222            .read()
223            .await
224            .get(&node_id)
225            .map(|s| s.is_in_backoff())
226            .unwrap_or(false)
227    }
228
229    /// Get the remaining backoff duration for a node, if any.
230    pub async fn get_node_backoff_remaining(&self, node_id: IrohNodeId) -> Option<Duration> {
231        let nodes = self.nodes.read().await;
232        let state = nodes.get(&node_id)?;
233        let until = state.backoff_until?;
234        let now = Instant::now();
235        if now < until { Some(until - now) } else { None }
236    }
237}
238
239#[derive(Debug, Snafu)]
240#[snafu(visibility(pub))]
241pub struct ClientRefError {
242    #[snafu(implicit)]
243    location: Location,
244}
245
246pub type ClientRefResult<T> = Result<T, ClientRefError>;
247
248/// Weak handle to [`Client`]
249#[derive(Debug, Clone)]
250pub struct ClientHandle(Weak<Client>);
251
252impl ClientHandle {
253    pub fn app_ref_opt(&self) -> Option<ClientRef<'_>> {
254        let client = self.0.upgrade()?;
255        Some(ClientRef {
256            client,
257            r: PhantomData,
258        })
259    }
260    pub fn client_ref(&self) -> ClientRefResult<ClientRef<'_>> {
261        let client = self.0.upgrade().context(ClientRefSnafu)?;
262        Ok(ClientRef {
263            client,
264            r: PhantomData,
265        })
266    }
267
268    pub fn db(&self) -> ClientRefResult<Arc<Database>> {
269        let client = self.0.upgrade().context(ClientRefSnafu)?;
270
271        Ok(client.db().clone())
272    }
273}
274
275impl From<Weak<Client>> for ClientHandle {
276    fn from(value: Weak<Client>) -> Self {
277        Self(value)
278    }
279}
280
281/// A strong reference to [`Client`]
282///
283/// It contains a phantom reference, to avoid attempts of
284/// storing it anywhere.
285#[derive(Clone)]
286pub struct ClientRef<'r> {
287    pub(crate) client: Arc<Client>,
288    pub(crate) r: PhantomData<&'r ()>,
289}
290
291impl ops::Deref for ClientRef<'_> {
292    type Target = Client;
293
294    fn deref(&self) -> &Self::Target {
295        &self.client
296    }
297}
298
299impl ClientRef<'_> {
300    /// Connect to a peer using the shared connection cache
301    ///
302    /// Returns a cached connection if available, otherwise creates a new one.
303    /// This is more efficient than `connect_uncached` when making repeated
304    /// connections to the same peer.
305    pub async fn connect_cached(&self, id: RostraId) -> ConnectResult<Connection> {
306        self.networking.connect_cached(id).await
307    }
308}
309
310/// The networked runtime for one Rostra identity.
311///
312/// Construct clients with [`Client::builder`]. The returned [`Arc<Self>`] owns
313/// all request handling and background work, which stops when the final strong
314/// reference is dropped.
315pub struct Client {
316    /// Weak self-reference that can be given out to components
317    pub(crate) handle: ClientHandle,
318
319    /// Our main identity (pkarr/ed25519_dalek keypair)
320    pub(crate) id: RostraId,
321
322    pub(crate) db: Arc<Database>,
323
324    active: AtomicBool,
325
326    /// Serializes the fallible transition into active/signing mode.
327    activation_lock: tokio::sync::Mutex<()>,
328
329    /// Networking layer (endpoint, pkarr, p2p_state, connection cache)
330    pub(crate) networking: Arc<crate::net::ClientNetworking>,
331
332    task_handles: Mutex<Vec<AbortOnDropHandle<()>>>,
333}
334
335#[bon::bon]
336impl Client {
337    /// Construct a client for `id`.
338    ///
339    /// Without `db`, the client uses temporary in-memory storage and does not
340    /// start full-client background synchronization tasks. Supplying a durable
341    /// `db` enables the supported full-client mode. The request handler starts
342    /// by default, background tasks start by default for full clients, and
343    /// client-created networking is relay-only unless `public_mode` is
344    /// explicitly enabled. A supplied `iroh_endpoint` retains its existing
345    /// transport and privacy policy instead.
346    #[builder(finish_fn(name = "build"))]
347    pub async fn new(
348        #[builder(start_fn)] id: RostraId,
349        #[builder(default = true)] start_request_handler: bool,
350        /// When false, skips spawning background tasks (head checker, event
351        /// fetchers, etc.) even when a DB is provided. Useful for tests.
352        #[builder(default = true)]
353        start_background_tasks: bool,
354        db: Option<Database>,
355        secret: Option<RostraIdSecretKey>,
356        /// When true, allows direct IP connections (exposes IP address).
357        /// When false (default), uses relay-only mode for privacy.
358        #[builder(default = false)]
359        public_mode: bool,
360        /// Pre-built iroh endpoint. If provided, uses this instead of
361        /// creating a new one. Useful for tests that need custom endpoint
362        /// configuration. The caller owns the endpoint's direct-transport and
363        /// privacy policy; `public_mode` does not reconfigure it. The caller
364        /// must also configure safe QUIC stream counts and receive
365        /// windows before binding. Post-handshake reductions cannot
366        /// retract transport credit that an endpoint already
367        /// advertised.
368        iroh_endpoint: Option<iroh::Endpoint>,
369        /// Pre-built pkarr client. If provided, uses this instead of
370        /// creating a new one. Since the pkarr client is identity-agnostic,
371        /// a single instance can be shared across all Rostra clients.
372        /// Use [`Client::make_pkarr_client`] to create one.
373        pkarr_client: Option<Arc<pkarr::Client>>,
374    ) -> InitResult<Arc<Self>> {
375        debug!(target: LOG_TARGET, id = %id, "Starting Rostra client");
376        let client_start = Instant::now();
377        let is_mode_full = db.is_some();
378
379        let pkarr_client = if let Some(pc) = pkarr_client {
380            pc
381        } else {
382            trace!(target: LOG_TARGET, id = %id, "Creating Pkarr client");
383            let pc = Self::make_pkarr_client()?;
384            debug!(target: LOG_TARGET, id = %id, elapsed_ms = %client_start.elapsed().as_millis(), "Pkarr client created");
385            pc
386        };
387
388        let endpoint = if let Some(ep) = iroh_endpoint {
389            ep
390        } else {
391            trace!(target: LOG_TARGET, id = %id, "Creating Iroh endpoint");
392            let ep =
393                Self::make_iroh_endpoint(db.as_ref().map(|s| s.iroh_secret()), public_mode).await?;
394            debug!(target: LOG_TARGET, id = %id, elapsed_ms = %client_start.elapsed().as_millis(), "Iroh endpoint created");
395            ep
396        };
397        let db: Arc<Database> = match db {
398            Some(db) => db,
399            _ => {
400                debug!(target: LOG_TARGET, id = %id, "Creating temporary in-memory database");
401                Database::new_in_memory(id).await?
402            }
403        }
404        .into();
405        trace!(target: LOG_TARGET, id = %id, "Creating client");
406        let networking = Arc::new(crate::net::ClientNetworking::new(
407            endpoint,
408            pkarr_client,
409            db.clone() as Arc<dyn crate::net::IdEndpointLookup>,
410        ));
411        let client = Arc::new_cyclic(|client| Self {
412            handle: client.clone().into(),
413            networking,
414            db,
415            id,
416            active: AtomicBool::new(false),
417            activation_lock: tokio::sync::Mutex::new(()),
418            task_handles: Mutex::new(Vec::new()),
419        });
420
421        trace!(target: LOG_TARGET, id = %id, "Starting client tasks");
422        if start_request_handler {
423            client.start_request_handler();
424        }
425
426        if is_mode_full && start_background_tasks {
427            client.start_head_update_broadcaster();
428            client.start_missing_event_fetcher();
429            client.start_missing_event_content_fetcher();
430            client.start_new_head_fetcher();
431            client.start_poll_follower_head_updates();
432            client.start_poll_followee_head_updates();
433            client.start_wot_head_sync();
434            client.start_news_score_updater();
435        }
436
437        if let Some(secret) = secret {
438            client.unlock_active(secret).await.context(ActivateSnafu)?;
439        }
440
441        trace!(target: LOG_TARGET, %id, "Client complete");
442        Ok(client)
443    }
444}
445
446#[bon::bon]
447impl Client {
448    /// Return the identity served by this client.
449    pub fn rostra_id(&self) -> RostraId {
450        self.id
451    }
452
453    /// Unlock signing operations and start signing-dependent background tasks.
454    ///
455    /// The secret must belong to [`Client::rostra_id`]. Calling this method
456    /// more than once is harmless after the first successful activation.
457    pub async fn unlock_active(&self, id_secret: RostraIdSecretKey) -> ActivateResult<()> {
458        let unlock_start = Instant::now();
459        ensure!(self.id == id_secret.id(), SecretMismatchSnafu);
460        let _activation_guard = self.activation_lock.lock().await;
461        if self.active.load(SeqCst) {
462            return Ok(());
463        }
464
465        let db = &self.db;
466
467        let our_endpoint = IrohNodeId::from_bytes(*self.networking.endpoint.id().as_bytes());
468        let endpoints = db.get_id_endpoints(self.rostra_id()).await;
469        debug!(target: LOG_TARGET, elapsed_ms = %unlock_start.elapsed().as_millis(), "Fetched id endpoints");
470
471        if let Some((_existing_id, _existing_record)) = endpoints
472            .iter()
473            .find(|((_ts, endpoint), _)| endpoint == &our_endpoint)
474        {
475            debug!(target: LOG_TARGET, "Existing node announcement found");
476            self.finish_activation(id_secret, Ok(()))?;
477        } else {
478            let announcement_result = self.publish_node_announcement(id_secret).await;
479            self.finish_activation(id_secret, announcement_result)?;
480            info!(target: LOG_TARGET, "Published node announcement");
481            debug!(target: LOG_TARGET, elapsed_ms = %unlock_start.elapsed().as_millis(), "Node announcement published");
482        }
483
484        debug!(target: LOG_TARGET, elapsed_ms = %unlock_start.elapsed().as_millis(), "unlock_active complete");
485        Ok(())
486    }
487
488    fn finish_activation(
489        &self,
490        id_secret: RostraIdSecretKey,
491        announcement_result: PostResult<()>,
492    ) -> ActivateResult<()> {
493        announcement_result.context(LocalAnnouncementStorageSnafu)?;
494        self.active.store(true, SeqCst);
495        self.start_pkarr_id_publisher(id_secret);
496        self.start_head_merger(id_secret);
497        Ok(())
498    }
499
500    pub async fn publish_node_announcement(&self, id_secret: RostraIdSecretKey) -> PostResult<()> {
501        self.publish_event(
502            id_secret,
503            content_kind::NodeAnnouncement::Iroh {
504                addr: IrohNodeId::from_bytes(*self.networking.endpoint.id().as_bytes()),
505            },
506        )
507        .call()
508        .await?;
509
510        Ok(())
511    }
512
513    /// Create a shared pkarr client.
514    ///
515    /// The pkarr client is identity-agnostic, so a single instance can
516    /// be reused across all Rostra clients via the `pkarr_client`
517    /// parameter on [`Client::builder`].
518    pub fn make_pkarr_client() -> InitResult<Arc<pkarr::Client>> {
519        Ok(Arc::new(
520            pkarr::Client::builder()
521                .relays(&["https://dns.iroh.link/pkarr"])
522                .expect("Can't fail")
523                .build()
524                .context(InitPkarrClientSnafu)?,
525        ))
526    }
527
528    pub(crate) async fn make_iroh_endpoint(
529        iroh_secret: impl Into<Option<iroh::SecretKey>>,
530        public_mode: bool,
531    ) -> InitResult<iroh::Endpoint> {
532        use iroh::endpoint::{QuicTransportConfig, VarInt, presets};
533        use iroh::{Endpoint, SecretKey};
534        let secret_key = iroh_secret.into().unwrap_or_else(SecretKey::generate);
535
536        // Use the n0 preset for relay transport and Pkarr/DNS address lookup.
537        // Rostra publishes its own tickets through Pkarr for each identity.
538        let transport = QuicTransportConfig::builder()
539            .max_concurrent_bidi_streams(VarInt::from_u32(32))
540            .max_concurrent_uni_streams(VarInt::from_u32(0))
541            .stream_receive_window(VarInt::from_u32(64 * 1024))
542            .receive_window(VarInt::from_u32(2 * 1024 * 1024))
543            .build();
544        let mut builder = Endpoint::builder(presets::N0)
545            .secret_key(secret_key)
546            .alpns(vec![ROSTRA_P2P_V0_ALPN.to_vec()])
547            .transport_config(transport);
548
549        // By default, use relay-only mode for privacy (no direct IP connections).
550        // In public mode, allow direct IP connections (useful for hosted nodes).
551        if !public_mode {
552            builder = builder.clear_ip_transports();
553        }
554
555        let ep = builder.bind().await.context(InitIrohClientSnafu)?;
556        let iroh_id_z32 = z32::encode(ep.id().as_bytes());
557        debug!(target: LOG_TARGET, iroh_id = %ep.id(), %iroh_id_z32, public_mode, "Created Iroh endpoint");
558        Ok(ep)
559    }
560
561    fn spawn_task(&self, future: impl Future<Output = ()> + Send + 'static) {
562        let handle = AbortOnDropHandle::new(tokio::spawn(future));
563        self.task_handles
564            .lock()
565            .expect("locking failed")
566            .push(handle);
567    }
568
569    pub(crate) fn start_pkarr_id_publisher(&self, secret_id: RostraIdSecretKey) {
570        self.spawn_task(PkarrIdPublisher::new(self, secret_id).run());
571    }
572
573    pub(crate) fn start_head_merger(&self, secret_id: RostraIdSecretKey) {
574        self.spawn_task(HeadMerger::new(self, secret_id).run());
575    }
576
577    pub(crate) fn start_request_handler(&self) {
578        self.spawn_task(RequestHandler::new(self, self.networking.endpoint.clone()).run());
579    }
580
581    pub(crate) fn start_head_update_broadcaster(&self) {
582        self.spawn_task(
583            crate::task::head_update_broadcaster::HeadUpdateBroadcaster::new(self).run(),
584        );
585    }
586    pub(crate) fn start_missing_event_fetcher(&self) {
587        self.spawn_task(MissingEventFetcher::new(self).run());
588    }
589    pub(crate) fn start_missing_event_content_fetcher(&self) {
590        self.spawn_task(MissingEventContentFetcher::new(self).run());
591    }
592
593    pub(crate) fn start_new_head_fetcher(&self) {
594        self.spawn_task(crate::task::new_head_fetcher::NewHeadFetcher::new(self).run());
595    }
596
597    pub(crate) fn start_poll_follower_head_updates(&self) {
598        self.spawn_task(
599            crate::task::poll_follower_head_updates::PollFollowerHeadUpdates::new(self).run(),
600        );
601    }
602
603    pub(crate) fn start_poll_followee_head_updates(&self) {
604        self.spawn_task(
605            crate::task::poll_followee_head_updates::PollFolloweeHeadUpdates::new(self).run(),
606        );
607    }
608
609    pub(crate) fn start_wot_head_sync(&self) {
610        self.spawn_task(crate::task::wot_head_sync::WotHeadSync::new(self).run());
611    }
612
613    pub(crate) fn start_news_score_updater(&self) {
614        self.spawn_task(crate::task::news_score_updater::NewsScoreUpdater::new(self).run());
615    }
616
617    pub(crate) async fn iroh_address(&self) -> WhateverResult<EndpointAddr> {
618        pub(crate) fn sanitize_endpoint_addr(endpoint_addr: EndpointAddr) -> EndpointAddr {
619            use iroh_base::TransportAddr;
620            pub(crate) fn is_ipv4_cgnat(ip: Ipv4Addr) -> bool {
621                matches!(ip.octets(), [100, b, ..] if (64..128).contains(&b))
622            }
623            let filtered_addrs = endpoint_addr
624                .addrs
625                .into_iter()
626                .filter(|addr| match addr {
627                    TransportAddr::Ip(socket_addr) => match socket_addr {
628                        std::net::SocketAddr::V4(ipv4) => {
629                            let ip = ipv4.ip();
630                            !ip.is_private()
631                                && !ip.is_link_local()
632                                && !is_ipv4_cgnat(*ip)
633                                && !ip.is_loopback()
634                                && !ip.is_multicast()
635                                && !ip.is_broadcast()
636                                && !ip.is_documentation()
637                        }
638                        std::net::SocketAddr::V6(ipv6) => {
639                            let ip = ipv6.ip();
640                            !ip.is_multicast()
641                                && !ip.is_loopback()
642                                // Unique Local Addresses (ULA)
643                                && (ip.to_bits() & !0x7f) != 0xfc00_0000_0000_0000_0000_0000_0000_0000
644                                // Link-Local Addresses
645                                && (ip.to_bits() & !0x3ff) != 0xfe80_0000_0000_0000_0000_0000_0000_0000
646                        }
647                    },
648                    TransportAddr::Relay(_) => true, // Keep relay addresses
649                    _ => true, // Keep any future address types
650                })
651                .collect();
652            EndpointAddr {
653                id: endpoint_addr.id,
654                addrs: filtered_addrs,
655            }
656        }
657
658        Ok(sanitize_endpoint_addr(self.networking.endpoint.addr()))
659    }
660
661    /// Subscribe to owned snapshots of the minimum current self-head
662    /// representative.
663    ///
664    /// The retained value is a deterministic default and does not imply that
665    /// the complete current head set is a singleton.
666    pub fn self_head_subscribe(&self) -> CurrentState<Option<ShortEventId>> {
667        self.db.self_head_subscribe()
668    }
669
670    /// Subscribe to newly accepted verified event content.
671    pub fn new_content_subscribe(&self) -> broadcast::Receiver<VerifiedEventContent> {
672        self.db.new_content_subscribe()
673    }
674
675    /// Subscribe to newly accepted social posts.
676    pub fn new_posts_subscribe(
677        &self,
678    ) -> broadcast::Receiver<(VerifiedEventContent, content_kind::SocialPost)> {
679        self.db.new_posts_subscribe()
680    }
681
682    /// Subscribe to newly accepted shoutbox messages.
683    pub fn new_shoutbox_subscribe(
684        &self,
685    ) -> broadcast::Receiver<(VerifiedEventContent, content_kind::Shoutbox)> {
686        self.db.new_shoutbox_subscribe()
687    }
688
689    /// Subscribe to lossy incremental exact new-head signals.
690    ///
691    /// Each signal names the accepted event that became a head. Consumers that
692    /// lag must recover from the database's complete durable head set.
693    pub fn new_heads_subscribe(&self) -> broadcast::Receiver<(RostraId, ShortEventId)> {
694        self.db.new_heads_subscribe()
695    }
696
697    /// Subscribe to deduplicated identities whose event history is incomplete.
698    pub fn ids_with_missing_events_subscribe(
699        &self,
700        capacity: usize,
701    ) -> dedup_chan::Receiver<RostraId> {
702        self.db.ids_with_missing_events_subscribe(capacity)
703    }
704
705    /// Access the identity's database and materialized views.
706    pub fn db(&self) -> &Arc<Database> {
707        &self.db
708    }
709
710    /// Return the deterministic representative of the current self-head set.
711    pub async fn events_head(&self) -> Option<ShortEventId> {
712        self.db.get_self_current_head().await
713    }
714
715    /// Create a weak handle that does not keep this client running.
716    pub fn handle(&self) -> ClientHandle {
717        self.handle.clone()
718    }
719
720    /// Access in-memory P2P connection state for debugging.
721    pub fn p2p_state(&self) -> &P2PState {
722        self.networking.p2p_state()
723    }
724
725    pub(crate) fn connection_cache(&self) -> &crate::connection_cache::ConnectionCache {
726        self.networking.connection_cache()
727    }
728
729    pub(crate) fn networking(&self) -> &Arc<crate::net::ClientNetworking> {
730        &self.networking
731    }
732
733    /// Returns our local Iroh node ID.
734    pub fn local_iroh_id(&self) -> IrohNodeId {
735        IrohNodeId::from_bytes(*self.networking.endpoint.id().as_bytes())
736    }
737
738    /// Resolve an identity's published transport and graph-head information.
739    pub async fn resolve_id_data(&self, id: RostraId) -> IdResolveResult<IdResolvedData> {
740        self.networking.resolve_id_data(id).await
741    }
742
743    /// Resolve an identity's compact transport ticket.
744    pub async fn resolve_id_ticket(&self, id: RostraId) -> IdResolveResult<CompactTicket> {
745        self.networking.resolve_id_ticket(id).await
746    }
747
748    /// Open a fresh typed RPC connection to an identity.
749    pub async fn connect_uncached(&self, id: RostraId) -> ConnectResult<Connection> {
750        self.networking.connect_uncached(id).await
751    }
752
753    /// Resolve an identity through Pkarr and open a fresh typed RPC connection.
754    pub async fn connect_by_pkarr_resolution(&self, id: RostraId) -> ConnectResult<Connection> {
755        self.networking.connect_by_pkarr_resolution(id).await
756    }
757
758    /// Open a typed RPC connection using a previously resolved compact ticket.
759    pub async fn connect_ticket(&self, ticket: CompactTicket) -> ConnectResult<Connection> {
760        self.networking.connect_ticket(ticket).await
761    }
762
763    /// Fetch an event and its content from its author or known followers.
764    ///
765    /// The caller-owned cache avoids repeating follower lookups while fetching
766    /// a batch of related events. The method returns `true` when content
767    /// was found and stored.
768    pub async fn fetch_event_content(
769        &self,
770        author_id: RostraId,
771        event_id: ShortEventId,
772        followers_cache: &mut std::collections::BTreeMap<RostraId, Vec<RostraId>>,
773    ) -> Result<bool, DbError> {
774        crate::util::rpc::get_event_content_from_followers(
775            self.networking(),
776            self.rostra_id(),
777            author_id,
778            event_id,
779            self.connection_cache(),
780            followers_cache,
781            self.db(),
782        )
783        .await
784    }
785
786    /// Synchronize an event and its ancestors from a set of candidate peers.
787    ///
788    /// This explicit synchronization boundary is useful when an integration
789    /// learns a remote head outside the client's normal background discovery.
790    /// It returns `true` when any new envelope or content was stored.
791    pub async fn sync_event_from_peers(
792        &self,
793        author_id: RostraId,
794        head: ShortEventId,
795        peers: &[RostraId],
796    ) -> Result<bool, DbError> {
797        crate::util::rpc::download_events_from_child(
798            author_id,
799            head,
800            self.networking(),
801            self.connection_cache(),
802            peers,
803            self.db(),
804        )
805        .await
806    }
807
808    pub(crate) fn pkarr_client(&self) -> Arc<pkarr::Client> {
809        self.networking.pkarr_client.clone()
810    }
811
812    pub(crate) async fn does_have_event(&self, _event_id: rostra_core::EventId) -> bool {
813        // TODO: check
814        false
815    }
816
817    /// Store verified event content, retaining author and event context on
818    /// error.
819    pub async fn store_event_with_content(
820        &self,
821        event_id: impl Into<ShortEventId>,
822        content: &VerifiedEventContent,
823    ) -> StoreEventResult<()> {
824        let event_id = event_id.into();
825        self.db
826            .try_process_event_with_content(content)
827            .await
828            .map(|_| ())
829            .map_err(|source| StoreEventError {
830                author_id: content.author(),
831                event_id,
832                source,
833            })
834    }
835
836    /// Store an oversized verified envelope without accepting its payload.
837    pub(crate) async fn store_event_too_large(&self, event: &VerifiedEvent) -> DbResult<()> {
838        self.db.try_process_event(event).await.map(|_| ())
839    }
840
841    pub(crate) fn event_size_limit(&self) -> u32 {
842        // TODO: take from db or something
843        16 * 1024 * 1024
844    }
845
846    /// Read and parse a secret identity key from a UTF-8 file.
847    pub async fn read_id_secret(path: &Path) -> IdSecretReadResult<RostraIdSecretKey> {
848        let content = tokio::fs::read_to_string(path).await.context(IoSnafu)?;
849        RostraIdSecretKey::from_str(&content).context(ParsingSnafu)
850    }
851
852    pub async fn check_published_id_state(&self) -> IdResolveResult<IdResolvedData> {
853        (|| async { self.resolve_id_data(self.id).await })
854            .retry(
855                backon::FibonacciBuilder::default()
856                    .with_jitter()
857                    .without_max_times(),
858            )
859            .when(|e|
860                // Retry only problems with doing the query itself
861                 matches!(e, IdResolveError::PkarrResolve))
862            .notify(|e, _| debug!(target: LOG_TARGET, err = %e.fmt_compact(), "Could not determine the state of published id"))
863            .await
864    }
865
866    #[builder]
867    pub async fn publish_event<C>(
868        &self,
869        #[builder(start_fn)] id_secret: RostraIdSecretKey,
870        #[builder(start_fn)] content: C,
871        replace: Option<ShortEventId>,
872    ) -> PostResult<VerifiedEvent>
873    where
874        C: content_kind::EventContentKind,
875    {
876        let current_head = self.db.get_self_current_head().await;
877        let aux_event = if replace.is_some() {
878            None
879        } else {
880            self.db.get_self_random_eventid().await
881        };
882
883        let (event, content) = Event::builder(&content)
884            .author(self.id)
885            .maybe_parent_prev(current_head)
886            .maybe_parent_aux(aux_event)
887            .maybe_delete(replace)
888            .build()?;
889
890        let signed_event = event.signed_by(id_secret);
891
892        let verified_event = VerifiedEvent::verify_signed(self.id, signed_event)
893            .expect("Can't fail to verify self-created event");
894        let verified_event_content =
895            rostra_core::event::VerifiedEventContent::verify(verified_event, content)
896                .expect("Can't fail to verify self-created content");
897        self.db
898            .try_process_event_with_content(&verified_event_content)
899            .await
900            .context(StorageSnafu)?;
901
902        Ok(verified_event)
903    }
904
905    pub async fn post_shoutbox(
906        &self,
907        id_secret: RostraIdSecretKey,
908        body: String,
909    ) -> PostResult<VerifiedEvent> {
910        self.publish_event(id_secret, content_kind::Shoutbox { djot_content: body })
911            .call()
912            .await
913    }
914
915    pub async fn social_post(
916        &self,
917        id_secret: RostraIdSecretKey,
918        body: String,
919        reply_to: Option<ExternalEventId>,
920        persona_tags: BTreeSet<PersonaTag>,
921    ) -> PostResult<VerifiedEvent> {
922        self.publish_event(
923            id_secret,
924            content_kind::SocialPost::new(body, reply_to, persona_tags),
925        )
926        .call()
927        .await
928    }
929
930    pub async fn social_news_post(
931        &self,
932        id_secret: RostraIdSecretKey,
933        body: String,
934        url: Option<url::Url>,
935        title: Option<String>,
936    ) -> PostResult<VerifiedEvent> {
937        self.publish_event(
938            id_secret,
939            content_kind::SocialPost::new(
940                body,
941                None,
942                BTreeSet::from([PersonaTag::new("news").expect("valid persona tag")]),
943            )
944            .with_news_fields(url, title),
945        )
946        .call()
947        .await
948    }
949
950    pub async fn set_social_vote(
951        &self,
952        id_secret: RostraIdSecretKey,
953        post_id: ExternalEventId,
954        upvote: Option<bool>,
955    ) -> PostResult<VerifiedEvent> {
956        self.publish_event(id_secret, content_kind::SocialVote::new(post_id, upvote))
957            .call()
958            .await
959    }
960
961    pub async fn get_self_social_vote(&self, post_id: ExternalEventId) -> Option<Option<bool>> {
962        self.db.get_social_vote(self.rostra_id(), post_id).await
963    }
964    pub async fn post_social_profile_update(
965        &self,
966        id_secret: RostraIdSecretKey,
967        display_name: String,
968        bio: String,
969        avatar: Option<(String, Vec<u8>)>,
970    ) -> PostResult<VerifiedEvent> {
971        let existing = self
972            .db
973            .get_social_profile(self.rostra_id())
974            .await
975            .map(|r| r.event_id);
976        self.publish_event(
977            id_secret,
978            content_kind::SocialProfileUpdate {
979                display_name,
980                bio,
981                avatar,
982            },
983        )
984        .maybe_replace(existing)
985        .call()
986        .await
987    }
988
989    pub async fn follow(
990        &self,
991        id_secret: RostraIdSecretKey,
992        followee_id: RostraId,
993        tags_selector: PersonasTagsSelector,
994    ) -> PostResult<VerifiedEvent> {
995        self.publish_event(
996            id_secret,
997            content_kind::Follow {
998                followee: followee_id,
999                selector: None,
1000                persona: None,
1001                persona_tags_selector: Some(tags_selector),
1002            },
1003        )
1004        .call()
1005        .await
1006    }
1007
1008    pub async fn unfollow(
1009        &self,
1010        id_secret: RostraIdSecretKey,
1011        followee: RostraId,
1012    ) -> PostResult<VerifiedEvent> {
1013        self.publish_event(
1014            id_secret,
1015            content_kind::Follow {
1016                followee,
1017                persona: None,
1018                selector: None,
1019                persona_tags_selector: None,
1020            },
1021        )
1022        .call()
1023        .await
1024    }
1025    pub async fn publish_omni_tbd(
1026        &self,
1027        id_secret: RostraIdSecretKey,
1028        body: String,
1029    ) -> PostResult<()> {
1030        pub(crate) const ACTIVE_RESERVATION_TIMEOUT: Duration = Duration::from_secs(120);
1031        let mut known_head = None;
1032        let mut active_reservation: Option<(CompactTicket, Instant)> = None;
1033        let mut event_and_content: Option<(SignedEvent, EventContentRaw)> = None;
1034
1035        'try_connect_to_active: loop {
1036            let published_id_data = self.check_published_id_state().await;
1037
1038            match published_id_data {
1039                Ok(published_id_data) => {
1040                    known_head = published_id_data.published.head.or(known_head);
1041                    let Some(ticket) = published_id_data.published.ticket else {
1042                        debug!(target: LOG_TARGET, "Not ticket to join this instance");
1043                        break 'try_connect_to_active;
1044                    };
1045
1046                    if let Some((active_ticket, start)) = active_reservation.as_ref() {
1047                        if active_ticket == &ticket {
1048                            if ACTIVE_RESERVATION_TIMEOUT < start.elapsed() {
1049                                debug!(target: LOG_TARGET, "Reservation stale");
1050                                break 'try_connect_to_active;
1051                            }
1052                        } else {
1053                            active_reservation = Some((ticket.clone(), Instant::now()));
1054                        }
1055                    } else {
1056                        active_reservation = Some((ticket.clone(), Instant::now()));
1057                    }
1058
1059                    let Ok(conn) = self.connect_ticket(ticket).await.inspect_err(|err| {
1060                        debug!(target: LOG_TARGET, err = %err.fmt_compact(), "Failed to connect to active instance");
1061                    }) else {
1062                        continue;
1063                    };
1064
1065                    if event_and_content.is_none() {
1066                        event_and_content = Some({
1067                            let (event, content) = Event::builder(&SocialPost::new(
1068                                body.clone(),
1069                                None,
1070                                BTreeSet::new(),
1071                            ))
1072                            .author(self.id)
1073                            .build()?;
1074
1075                            (event.signed_by(id_secret), content)
1076                        });
1077                    }
1078
1079                    let (signed_event, raw_content) =
1080                        event_and_content.as_ref().expect("Must be set by now");
1081                    match conn.feed_event(*signed_event, raw_content.clone()).await {
1082                        Ok(_) => {
1083                            debug!(target: LOG_TARGET, "Published");
1084                            return Ok(());
1085                        }
1086                        Err(RpcError::Failed {
1087                            return_code: FeedEventResponse::RETURN_CODE_ALREADY_HAVE,
1088                        }) => {
1089                            debug!(target: LOG_TARGET, "Already published");
1090                            return Ok(());
1091                        }
1092                        Err(err) => {
1093                            debug!(target: LOG_TARGET, err = %err.fmt_compact(), "Could not upload to active instance");
1094                        }
1095                    }
1096                }
1097                Err(_) => todo!(),
1098            }
1099        }
1100
1101        Ok(())
1102    }
1103
1104    /// Subscribe to owned snapshots of the retained self-followee projection.
1105    pub fn self_followees_subscribe(
1106        &self,
1107    ) -> CurrentState<Arc<HashMap<RostraId, IdsFolloweesRecord>>> {
1108        self.db.self_followees_subscribe()
1109    }
1110
1111    /// Subscribe to owned snapshots of the retained self-follower projection.
1112    pub fn self_followers_subscribe(
1113        &self,
1114    ) -> CurrentState<Arc<HashMap<RostraId, IdsFollowersRecord>>> {
1115        self.db.self_followers_subscribe()
1116    }
1117
1118    /// Subscribe to owned snapshots of the retained Web-of-Trust projection.
1119    pub fn self_wot_subscribe(&self) -> CurrentState<Arc<WotData>> {
1120        self.db.self_wot_subscribe()
1121    }
1122}
1123
1124#[cfg(test)]
1125mod tests {
1126    use std::sync::atomic::Ordering::SeqCst;
1127    use std::time::Duration;
1128
1129    use iroh::endpoint::presets;
1130    use rostra_client_db::{Database, DbError, EventContentState};
1131    use rostra_core::event::{Event, EventContentRaw, EventKind};
1132    use rostra_core::id::{RostraIdSecretKey, ToShort as _};
1133    use rostra_p2p::connection::FeedEventResponse;
1134    use rostra_p2p::{Connection, RpcError};
1135    use rostra_p2p_api::ROSTRA_P2P_V0_ALPN;
1136
1137    use super::Client;
1138    use crate::error::PostError;
1139
1140    #[test_log::test(tokio::test(flavor = "multi_thread"))]
1141    async fn failed_announcement_does_not_commit_activation_and_retry_can_start_tasks() {
1142        let secret = RostraIdSecretKey::from_bytes([51; 32]);
1143        let endpoint = iroh::Endpoint::builder(presets::Minimal)
1144            .relay_mode(iroh::RelayMode::Disabled)
1145            .alpns(vec![ROSTRA_P2P_V0_ALPN.to_vec()])
1146            .bind()
1147            .await
1148            .expect("test endpoint");
1149        let client = Client::builder(secret.id())
1150            .iroh_endpoint(endpoint)
1151            .start_request_handler(false)
1152            .start_background_tasks(false)
1153            .build()
1154            .await
1155            .expect("test client");
1156
1157        client
1158            .finish_activation(
1159                secret,
1160                Err(PostError::Storage {
1161                    source: DbError::Overflow,
1162                }),
1163            )
1164            .expect_err("announcement storage failure");
1165        assert!(!client.active.load(SeqCst));
1166        assert!(client.task_handles.lock().expect("task handles").is_empty());
1167
1168        client
1169            .finish_activation(secret, Ok(()))
1170            .expect("activation retry");
1171        assert!(client.active.load(SeqCst));
1172        assert_eq!(
1173            client.task_handles.lock().expect("task handles").len(),
1174            2,
1175            "the retry starts each signing task exactly once"
1176        );
1177    }
1178
1179    #[test_log::test(tokio::test(flavor = "multi_thread"))]
1180    async fn oversized_feed_event_retains_pruned_envelope() {
1181        let secret = RostraIdSecretKey::from_bytes([52; 32]);
1182        let lookup = iroh::address_lookup::memory::MemoryLookup::new();
1183        let server_endpoint = iroh::Endpoint::builder(presets::Minimal)
1184            .relay_mode(iroh::RelayMode::Disabled)
1185            .alpns(vec![ROSTRA_P2P_V0_ALPN.to_vec()])
1186            .address_lookup(lookup.clone())
1187            .bind()
1188            .await
1189            .expect("server endpoint");
1190        let server_id = server_endpoint.id();
1191        lookup.add_endpoint_info(server_endpoint.addr());
1192        let client = Client::builder(secret.id())
1193            .db(Database::new_in_memory(secret.id())
1194                .await
1195                .expect("in-memory database"))
1196            .iroh_endpoint(server_endpoint)
1197            .start_background_tasks(false)
1198            .build()
1199            .await
1200            .expect("server client");
1201        let caller_endpoint = iroh::Endpoint::builder(presets::Minimal)
1202            .relay_mode(iroh::RelayMode::Disabled)
1203            .alpns(vec![ROSTRA_P2P_V0_ALPN.to_vec()])
1204            .address_lookup(lookup)
1205            .bind()
1206            .await
1207            .expect("caller endpoint");
1208        let connection = Connection::from(
1209            caller_endpoint
1210                .connect(server_id, ROSTRA_P2P_V0_ALPN)
1211                .await
1212                .expect("connect to server"),
1213        );
1214        let content = EventContentRaw::new(vec![0; client.event_size_limit() as usize + 1]);
1215        let event = Event::builder_raw_content()
1216            .author(secret.id())
1217            .kind(EventKind::NULL)
1218            .content(&content)
1219            .build()
1220            .signed_by(secret);
1221        let event_id = event.event.compute_id().to_short();
1222
1223        let error = tokio::time::timeout(
1224            Duration::from_secs(5),
1225            connection.feed_event(event, content),
1226        )
1227        .await
1228        .expect("oversized event response")
1229        .expect_err("oversized event must not transfer its content");
1230
1231        assert!(matches!(
1232            error,
1233            RpcError::Failed {
1234                return_code: FeedEventResponse::RETURN_CODE_ALREADY_HAVE
1235            }
1236        ));
1237        assert_eq!(
1238            client.db().get_event_content_state(event_id).await,
1239            Some(EventContentState::Pruned)
1240        );
1241    }
1242}