rostra-client 0.1.3

Integration runtime for Rostra peer-to-peer clients
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
use std::collections::HashSet;
use std::sync::Arc;

use futures::future::BoxFuture;
use futures::stream::{FuturesUnordered, StreamExt as _};
use iroh_base::EndpointAddr;
use rostra_client_db::Database;
use rostra_core::Timestamp;
use rostra_core::event::IrohNodeId;
use rostra_core::id::{RostraId, ToShort as _};
use rostra_p2p::ConnectionSnafu;
use rostra_p2p::connection::Connection;
use rostra_p2p_api::ROSTRA_P2P_V0_ALPN;
use rostra_util_error::FmtCompact as _;
use rostra_util_fmt::AsFmtOption as _;
use snafu::{OptionExt as _, ResultExt as _};
use tracing::{debug, trace};

use super::{RRECORD_HEAD_KEY, RRECORD_P2P_KEY, get_rrecord_typed};
use crate::client::{NodeSource, P2PState};
use crate::connection_cache::ConnectionCache;
use crate::error::{
    ConnectError, ConnectIrohSnafu, ConnectResult, IdResolveResult, InvalidIdSnafu,
    MissingTicketSnafu, NodeInBackoffSnafu, PkarrResolveSnafu, RRecordSnafu, ResolveSnafu,
};
// ConnectIrohSnafu is used for .context() in connect_ticket
use crate::id::{CompactTicket, IdPublishedData, IdResolvedData};

const LOG_TARGET: &str = "rostra::client-net";

/// Trait for looking up known iroh node IDs for a given RostraId.
///
/// This abstraction allows `ClientNetworking` to operate without a direct
/// database dependency, making it easier to test networking in isolation.
pub trait IdEndpointLookup: Send + Sync {
    fn get_node_ids(&self, id: RostraId) -> BoxFuture<'_, HashSet<IrohNodeId>>;
}

impl IdEndpointLookup for Database {
    fn get_node_ids(&self, id: RostraId) -> BoxFuture<'_, HashSet<IrohNodeId>> {
        Box::pin(async move {
            self.get_id_endpoints(id)
                .await
                .into_keys()
                .map(|(_ts, node_id)| node_id)
                .collect()
        })
    }
}

/// Result of attempting to connect to an endpoint.
#[derive(Debug)]
pub enum EndpointConnectResult {
    /// Successfully connected
    Success(Connection),
    /// Connection failed
    Failed(ConnectError),
    /// Node is in backoff, should not attempt
    InBackoff,
    /// Skipped (e.g., trying to connect to self)
    Skipped,
}

/// Networking layer for the Rostra client.
///
/// Handles all peer-to-peer connection logic including:
/// - Direct endpoint connections with backoff
/// - Parallel endpoint probing for a given RostraId
/// - Pkarr-based endpoint resolution
/// - Connection caching
pub struct ClientNetworking {
    pub(crate) endpoint: iroh::Endpoint,
    pub(crate) pkarr_client: Arc<pkarr::Client>,
    pub(crate) p2p_state: P2PState,
    pub(crate) connection_cache: ConnectionCache,
    id_endpoint_lookup: Arc<dyn IdEndpointLookup>,
}

impl ClientNetworking {
    pub fn new(
        endpoint: iroh::Endpoint,
        pkarr_client: Arc<pkarr::Client>,
        id_endpoint_lookup: Arc<dyn IdEndpointLookup>,
    ) -> Self {
        Self {
            endpoint,
            pkarr_client,
            p2p_state: P2PState::new(),
            connection_cache: ConnectionCache::new(),
            id_endpoint_lookup,
        }
    }

    /// Access in-memory P2P connection state for debugging.
    pub fn p2p_state(&self) -> &P2PState {
        &self.p2p_state
    }

    /// Access the shared connection cache.
    pub fn connection_cache(&self) -> &ConnectionCache {
        &self.connection_cache
    }

    /// Connect to a peer using the shared connection cache.
    ///
    /// Returns a cached connection if available, otherwise creates a new one.
    pub async fn connect_cached(&self, id: RostraId) -> ConnectResult<Connection> {
        self.connection_cache.get_or_connect(self, id).await
    }

    /// Connect to a specific iroh endpoint with backoff handling.
    ///
    /// This is the core connection function that:
    /// - Checks if the node is in backoff before attempting
    /// - Updates p2p_state on success/failure
    /// - Resets backoff on success
    /// - Increases backoff on failure (exponential, capped at 10 minutes)
    ///
    /// Returns `EndpointConnectResult` to indicate the outcome.
    ///
    /// Note: The connection+ping logic here is partially duplicated in
    /// `connect_uncached`'s parallel connection loop. See that function's
    /// comments for why it doesn't use this method.
    pub async fn connect_to_endpoint(
        &self,
        endpoint_addr: EndpointAddr,
        source: NodeSource,
        rostra_id: Option<RostraId>,
    ) -> EndpointConnectResult {
        let node_id = IrohNodeId::from_bytes(*endpoint_addr.id.as_bytes());

        // Skip connecting to our own endpoint
        if endpoint_addr.id == self.endpoint.id() {
            return EndpointConnectResult::Skipped;
        }

        // Check if node is in backoff
        if self.p2p_state.is_node_in_backoff(node_id).await {
            if let Some(remaining) = self.p2p_state.get_node_backoff_remaining(node_id).await {
                trace!(
                    target: LOG_TARGET,
                    %node_id,
                    remaining_secs = remaining.as_secs(),
                    "Node is in backoff, skipping connection attempt"
                );
            }
            return EndpointConnectResult::InBackoff;
        }

        // Track attempt
        let now = Timestamp::now();
        self.p2p_state
            .update_node(node_id, |state| {
                state.last_attempt = Some(now);
                state.source = source;
                state.rostra_id = rostra_id;
            })
            .await;

        debug!(
            target: LOG_TARGET,
            iroh_id = %endpoint_addr.id,
            rostra_id = %rostra_id.map(|id| id.to_short().to_string()).unwrap_or_default(),
            "Connecting to endpoint"
        );

        // Attempt connection
        let conn_result = self
            .endpoint
            .connect(endpoint_addr, ROSTRA_P2P_V0_ALPN)
            .await;

        trace!(
            target: LOG_TARGET,
            %node_id,
            err = %conn_result.as_ref().err().fmt_option(),
            "Iroh connect result"
        );

        match conn_result {
            Ok(conn) => {
                let conn = Connection::from(conn);

                // Verify connection with ping
                let ping_result = conn.ping(0).await;
                trace!(
                    target: LOG_TARGET,
                    %node_id,
                    err = %ping_result.as_ref().err().fmt_option(),
                    "Ping result"
                );

                match ping_result {
                    Ok(_) => {
                        let now = Timestamp::now();
                        self.p2p_state
                            .update_node(node_id, |state| state.record_success(now))
                            .await;
                        if let Some(id) = rostra_id {
                            self.p2p_state
                                .update(id, |state| state.last_success = Some(now))
                                .await;
                        }
                        debug!(
                            target: LOG_TARGET,
                            %node_id,
                            rostra_id = %rostra_id.fmt_option(),
                            "Connected to endpoint successfully"
                        );
                        EndpointConnectResult::Success(conn)
                    }
                    Err(err) => {
                        let now = Timestamp::now();
                        self.p2p_state
                            .update_node(node_id, |state| state.record_failure(now))
                            .await;
                        debug!(
                            target: LOG_TARGET,
                            %node_id,
                            err = %err.fmt_compact(),
                            "Ping failed after connection"
                        );
                        EndpointConnectResult::Failed(ConnectError::PingFailed { source: err })
                    }
                }
            }
            Err(err) => {
                let now = Timestamp::now();
                self.p2p_state
                    .update_node(node_id, |state| state.record_failure(now))
                    .await;
                if let Some(id) = rostra_id {
                    self.p2p_state
                        .update(id, |state| state.last_failure = Some(now))
                        .await;
                }
                debug!(
                    target: LOG_TARGET,
                    %node_id,
                    err = %err.fmt_compact(),
                    "Failed to connect to endpoint"
                );
                EndpointConnectResult::Failed(ConnectError::ConnectIroh { source: err })
            }
        }
    }

    /// Connect to a RostraId by trying all known endpoints in parallel.
    ///
    /// Note: The parallel loop below duplicates some logic from
    /// `connect_to_endpoint` rather than calling it. This is intentional
    /// because:
    /// 1. The spawned futures cannot borrow `&self` (Rust async limitation)
    /// 2. We want to check backoff BEFORE spawning futures (not inside them)
    /// 3. We want to update state AFTER futures complete (in the main loop, not
    ///    racing inside futures)
    /// 4. The connection+ping code is simple (~10 lines) and clearer when
    ///    inline
    pub async fn connect_uncached(&self, id: RostraId) -> ConnectResult<Connection> {
        let now = Timestamp::now();
        self.p2p_state
            .update(id, |state| state.last_attempt = Some(now))
            .await;

        let node_ids = self.id_endpoint_lookup.get_node_ids(id).await;

        trace!(
            target: LOG_TARGET,
            %id,
            num_endpoints = node_ids.len(),
            "Connecting to peer, trying known endpoints"
        );

        // Try all known endpoints in parallel
        let mut connection_futures = FuturesUnordered::new();

        for node_id in node_ids.iter().copied() {
            let Ok(pub_key) = iroh::PublicKey::from_bytes(&node_id.to_bytes()) else {
                debug!(target: LOG_TARGET, %id, "Invalid iroh id for rostra id found");
                continue;
            };

            // Check backoff before spawning the future
            if self.p2p_state.is_node_in_backoff(node_id).await {
                trace!(
                    target: LOG_TARGET,
                    %node_id,
                    %id,
                    "Node is in backoff, skipping"
                );
                continue;
            }

            // Track attempt per node
            let now = Timestamp::now();
            self.p2p_state
                .update_node(node_id, |state| {
                    state.last_attempt = Some(now);
                    state.source = NodeSource::NodeAnnouncement;
                    state.rostra_id = Some(id);
                })
                .await;

            let endpoint = self.endpoint.clone();
            let our_id = self.endpoint.id();
            connection_futures.push(async move {
                if pub_key == our_id {
                    // Skip connecting to our own Id
                    return (
                        node_id,
                        None,
                        Err::<Connection, _>("skipped: own endpoint".to_string()),
                    );
                }

                let result = async {
                    let conn_result = endpoint.connect(pub_key, ROSTRA_P2P_V0_ALPN).await;
                    trace!(target: LOG_TARGET, %node_id, err = %conn_result.as_ref().err().fmt_option(), "Iroh connect result");
                    let conn = Connection::from(conn_result.context(ConnectionSnafu)?);

                    // Verify connection with ping
                    let ping_result = conn.ping(0).await;
                    trace!(target: LOG_TARGET, %node_id, err = %ping_result.as_ref().err().fmt_option(), "Ping result");
                    ping_result?;
                    Ok::<_, rostra_p2p::RpcError>(conn)
                }
                .await;
                let err_str = result.as_ref().err().map(|e| e.fmt_compact().to_string());
                (node_id, err_str, result.map_err(|e| e.to_string()))
            });
        }

        // Try all connections in parallel, take first success
        while let Some((node_id, err_detail, result)) = connection_futures.next().await {
            match result {
                Ok(conn) => {
                    let now = Timestamp::now();
                    self.p2p_state
                        .update(id, |state| state.last_success = Some(now))
                        .await;
                    self.p2p_state
                        .update_node(node_id, |state| state.record_success(now))
                        .await;
                    debug!(
                        target: LOG_TARGET,
                        %id,
                        %node_id,
                        "Successfully connected to peer via known endpoint"
                    );
                    return Ok(conn);
                }
                Err(_) => {
                    let now = Timestamp::now();
                    self.p2p_state
                        .update_node(node_id, |state| state.record_failure(now))
                        .await;
                    trace!(
                        target: LOG_TARGET,
                        %id,
                        %node_id,
                        err = %err_detail.as_deref().unwrap_or("unknown"),
                        "Failed to connect to known endpoint"
                    );
                }
            }
        }

        if !node_ids.is_empty() {
            trace!(
                target: LOG_TARGET,
                %id,
                "All known endpoints failed, trying pkarr resolution"
            );
        }

        // Fall back to pkarr if no known endpoints worked
        self.connect_by_pkarr_resolution(id).await
    }

    pub async fn connect_by_pkarr_resolution(&self, id: RostraId) -> ConnectResult<Connection> {
        let ticket = self.resolve_id_ticket(id).await.context(ResolveSnafu)?;

        let endpoint_addr = EndpointAddr::from(ticket);
        let node_id = IrohNodeId::from_bytes(*endpoint_addr.id.as_bytes());

        match self
            .connect_to_endpoint(endpoint_addr, NodeSource::Pkarr, Some(id))
            .await
        {
            EndpointConnectResult::Success(conn) => Ok(conn),
            EndpointConnectResult::Failed(err) => Err(err),
            EndpointConnectResult::InBackoff => {
                if let Some(remaining) = self.p2p_state.get_node_backoff_remaining(node_id).await {
                    trace!(
                        target: LOG_TARGET,
                        %id,
                        %node_id,
                        remaining_secs = remaining.as_secs(),
                        "Cannot connect to peer - node is in backoff"
                    );
                }
                Err(NodeInBackoffSnafu.build())
            }
            EndpointConnectResult::Skipped => Err(ConnectError::ResolvedToSelf),
        }
    }

    pub async fn connect_ticket(&self, ticket: CompactTicket) -> ConnectResult<Connection> {
        // Note: connect_ticket doesn't use backoff since tickets are typically
        // provided by users and should be attempted regardless of previous failures
        Ok(self
            .endpoint
            .connect(ticket, ROSTRA_P2P_V0_ALPN)
            .await
            .context(ConnectIrohSnafu)?
            .into())
    }

    pub async fn resolve_id_data(&self, id: RostraId) -> IdResolveResult<IdResolvedData> {
        let public_key = pkarr::PublicKey::try_from(id).context(InvalidIdSnafu)?;
        let domain = public_key.to_string();
        let packet = self
            .pkarr_client
            .resolve(&public_key)
            .await
            .context(PkarrResolveSnafu)?;

        let timestamp = packet.timestamp();
        let ticket = get_rrecord_typed(&packet, &domain, RRECORD_P2P_KEY).context(RRecordSnafu)?;
        let head = get_rrecord_typed(&packet, &domain, RRECORD_HEAD_KEY).context(RRecordSnafu)?;

        trace!(
            target: LOG_TARGET,
            %id,
            ticket = %ticket.fmt_option(),
            head = %head.fmt_option(),
            "Resolved Id"
        );

        Ok(IdResolvedData {
            published: IdPublishedData { ticket, head },
            timestamp: timestamp.as_u64(),
        })
    }

    pub async fn resolve_id_ticket(&self, id: RostraId) -> IdResolveResult<CompactTicket> {
        self.resolve_id_data(id)
            .await?
            .published
            .ticket
            .context(MissingTicketSnafu)
    }
}