1pub mod config;
17pub mod constants;
19pub mod errors;
21pub mod observer;
22pub mod path;
24pub mod protocol;
26#[cfg(feature = "testing")]
29pub mod testing;
30
31mod multiaddrs;
32pub mod trace_context;
34
35pub type HoprMessageSender = trace_context::ContextSender<(DestinationRouting, ApplicationDataOut)>;
37
38#[cfg(feature = "capture")]
39mod capture;
40mod pipeline;
41pub mod socket;
42
43use std::{
44 sync::{Arc, OnceLock},
45 time::Duration,
46};
47
48use constants::MAXIMUM_MSG_OUTGOING_BUFFER_SIZE;
49use futures::{FutureExt, SinkExt, StreamExt, channel::mpsc::Sender, stream::select_with_strategy};
50use futures_concurrency::stream::StreamExt as ConcurrentStreamExt;
51pub use hopr_api::{
52 Multiaddr, PeerId,
53 network::{Health, traits::NetworkView},
54 types::{
55 crypto::{
56 keypairs::{ChainKeypair, Keypair, OffchainKeypair},
57 types::{HalfKeyChallenge, Hash, OffchainPublicKey, SimplePseudonym},
58 },
59 internal::{prelude::HoprPseudonym, routing::RoutingOptions},
60 },
61};
62use hopr_api::{
63 chain::{ChainKeyOperations, ChainReadAccountOperations, ChainReadChannelOperations, ChainValues},
64 ct::{CoverTrafficGeneration, ProbingTrafficGeneration},
65 graph::{NetworkGraphUpdate, NetworkGraphView, traits::EdgeObservableRead},
66 network::{BoxedProcessFn, NetworkStreamControl},
67 types::primitive::prelude::*,
68};
69pub use hopr_crypto_packet::HoprPixSpec;
70pub use hopr_protocol_app::prelude::{ApplicationData, ApplicationDataIn, ApplicationDataOut, Tag};
71pub use hopr_protocol_hopr::{MIN_TRACKED_PACKETS, MemorySurbStore, SurbStore};
72pub use hopr_protocol_pix::PixSpec;
77pub use hopr_protocol_pix::RecoveredSsa;
78use hopr_protocol_pix::ShareResolution;
79pub use hopr_transport_mixer as mixer;
85pub use hopr_transport_probe::{NeighborTelemetry, PathTelemetry, errors::ProbeError, ping::PingQueryReplier};
86use hopr_transport_probe::{
87 Probe,
88 ping::{PingConfig, Pinger},
89};
90pub use hopr_transport_session as session;
91use hopr_transport_session::{
92 AdmissionToken, AgreedSsaQuota, DispatchResult, HoprSessionInPixEvent, HoprSessionOutPixEvent, PixToolbox,
93 SessionManager, SessionManagerConfig, SurbAdmissionControl,
94};
95pub use hopr_transport_session::{
96 Capabilities as SessionCapabilities, Capability as SessionCapability, FlowControlConfig, HoprSession,
97 IncomingSession, InvalidPixParams, LOCAL_PIX_SUITE, PixParams, SESSION_MTU, SURB_SIZE, ServiceId,
98 SessionAdmissionReply, SessionAdmissionSink, SessionClientConfig, SessionId, SessionTarget, SurbBalancerConfig,
99 errors::{SessionManagerError, TransportSessionError},
100};
101#[cfg(feature = "telemetry")]
102pub use hopr_transport_session::{SessionAckMode, SessionLifecycleState};
103#[cfg(feature = "runtime-tokio")]
104pub use hopr_transport_session::{transfer_session, transfer_session_datagram};
105pub use hopr_transport_tag_allocator::TagAllocatorConfig;
106use hopr_utils::{
107 network_types::{
108 crossfire_sink::{CrossfireSink, bounded_sink_channel},
109 prelude::*,
110 },
111 runtime::AbortableList,
112};
113pub use multiaddr::Protocol;
114use tracing::{Instrument, debug, warn};
115
116#[cfg(feature = "runtime-tokio")]
117use crate::path::BackgroundPathCacheRefreshable;
118pub use crate::{
119 config::HoprProtocolConfig,
120 observer::{TransportEvent, TransportObserver},
121 protocol::PeerProtocolCounterRegistry,
122};
123use crate::{
124 config::PixGlobalConfig,
125 constants::SESSION_INITIATION_TIMEOUT_BASE,
126 errors::HoprTransportError,
127 multiaddrs::strip_p2p_protocol,
128 path::{HoprGraphPathSelector, PathPlanner},
129 pipeline::HoprPacketPipelineBuilder,
130 socket::HoprSocket,
131};
132
133pub const APPLICATION_TAG_RANGE: std::ops::Range<Tag> = Tag::APPLICATION_TAG_RANGE;
134
135pub use hopr_api as api;
136use hopr_api::{
137 chain::{ChainReadTicketOperations, ChainWriteTicketOperations, PixDepositSecret},
138 node::{PixAddressId, PixDepositAddressReceived, PixEvent, PixNewDepositAddress, PixPrivateKeyRecovered},
139 tickets::TicketFactory,
140 types::internal::routing::DestinationRouting,
141};
142use hopr_crypto_packet::HoprShareResolution;
143use rust_stream_ext_concurrent::then_concurrent::StreamThenConcurrentExt;
144
145lazy_static::lazy_static! {
146 static ref RANDOM_DATA: [u8; 400] = hopr_api::types::crypto_random::random_bytes();
147}
148
149#[cfg(all(feature = "telemetry", not(test)))]
150lazy_static::lazy_static! {
151 static ref METRIC_SURB_GENERATION_BUMPS: hopr_api::types::telemetry::SimpleCounter =
152 hopr_api::types::telemetry::SimpleCounter::new(
153 "hopr_surb_generation_bumps_total",
154 "SURB generation bumps after a dead relayer verdict",
155 )
156 .unwrap();
157 static ref METRIC_SURB_PENDING_LOST: hopr_api::types::telemetry::SimpleCounter =
158 hopr_api::types::telemetry::SimpleCounter::new(
159 "hopr_surb_pending_lost_total",
160 "SURB records the capacity-bounded pending map could not hold and evicted before their replies came home: an evicted record settles no race and is never written off. A non-zero rate means the map is undersized for the node's outstanding SURBs; raise surb_store.pending_surb_max_bytes",
161 )
162 .unwrap();
163}
164
165const SURB_BUFFER_TARGET_NUMERATOR: usize = 2;
173const SURB_BUFFER_TARGET_DENOMINATOR: usize = 3;
174
175const fn surb_buffer_target_ceiling(rb_capacity: usize) -> usize {
180 rb_capacity.saturating_mul(SURB_BUFFER_TARGET_NUMERATOR) / SURB_BUFFER_TARGET_DENOMINATOR
183}
184
185struct StoreSurbAdmission {
194 store: MemorySurbStore,
195}
196
197impl SurbAdmissionControl for StoreSurbAdmission {
198 fn admit(&self, pseudonym: &SessionId, expected_surbs: usize) -> AdmissionToken {
199 AdmissionToken::from_raw(self.store.admit(pseudonym, expected_surbs))
200 }
201
202 fn retire(&self, pseudonym: &SessionId, token: AdmissionToken) {
203 self.store.retire(pseudonym, token.into_raw());
204 }
205
206 fn raise_target(&self, pseudonym: &SessionId, token: AdmissionToken, expected_surbs: usize) {
207 self.store
208 .raise_admitted_capacity(pseudonym, token.into_raw(), expected_surbs);
209 }
210}
211
212const COUNTER_FLUSH_ACK_GRACE_DIVISOR: u32 = 3;
218
219fn counter_flush_ack_grace(flush_interval: Duration) -> Duration {
221 flush_interval / COUNTER_FLUSH_ACK_GRACE_DIVISOR
222}
223
224const SURB_DEGRADED_NOTIFY_PERIOD_ENV: &str = "HOPR_SESSION_SURB_DEGRADED_NOTIFY_PERIOD_MS";
226
227fn surb_degraded_notify_period_override(raw: Option<&str>, configured: Option<Duration>) -> Option<Duration> {
234 raw.and_then(|s| s.parse::<u64>().ok())
235 .map(|ms| Some(Duration::from_millis(ms)))
236 .unwrap_or(configured)
237}
238
239pub fn peer_id_to_public_key(peer_id: &PeerId) -> crate::errors::Result<OffchainPublicKey> {
246 OffchainPublicKey::from_peerid(peer_id).map_err(|e| {
247 crate::errors::HoprTransportError::Other(anyhow::anyhow!(
248 "failed to convert peer_id ({:?}) to an offchain public key: {e}",
249 peer_id
250 ))
251 })
252}
253
254#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq, strum::Display)]
255pub enum HoprTransportProcess {
256 #[strum(to_string = "component responsible for the transport medium (libp2p swarm)")]
257 Medium,
258 #[strum(to_string = "HOPR packet pipeline ({0})")]
259 Pipeline(protocol::PacketPipelineProcesses),
260 #[strum(to_string = "session manager sub-process #{0}")]
261 SessionsManagement(usize),
262 #[strum(to_string = "network probing sub-process: {0}")]
263 Probing(hopr_transport_probe::HoprProbeProcess),
264 #[cfg(feature = "runtime-tokio")]
265 #[strum(to_string = "path cache refresh")]
266 PathRefresh,
267 #[strum(to_string = "pix protocol event transformation")]
268 PixEvents,
269 #[strum(to_string = "sync of outgoing ticket indices")]
270 OutgoingIndexSync,
271 #[strum(to_string = "periodic protocol counter flush")]
272 CounterFlush,
273 SurbFlush,
275 #[strum(to_string = "mixer→wire forwarder")]
276 MixerForwarder,
277 #[cfg(feature = "capture")]
278 #[strum(to_string = "packet capture")]
279 Capture,
280}
281
282async fn dispatch_incoming_messages<G, In, Out>(
285 rx_from_protocol: In,
286 probe_classifier: hopr_transport_probe::ProbeClassifierState<G>,
287 unresolved_routing_msg_tx_for_task: HoprMessageSender,
288 smgr: Arc<HoprSessionManager>,
289 on_incoming_data_tx: Out,
290) where
291 G: NetworkGraphUpdate + Clone + Send + Sync + 'static,
292 In: futures::Stream<Item = trace_context::WithContext<(HoprPseudonym, ApplicationDataIn)>>,
293 Out: futures::Sink<ApplicationDataIn> + Unpin,
294{
295 rx_from_protocol
296 .filter_map(move |message| {
297 let classifier = probe_classifier.clone();
298 let push = unresolved_routing_msg_tx_for_task.clone();
299 let (value, span) = message.into_parts();
300 let output_span = span.clone();
301 async move {
302 match classifier.classify(push, value.0, value.1).await {
303 hopr_transport_probe::ProbeDispatch::Consumed => None,
304 hopr_transport_probe::ProbeDispatch::Passthrough(pseudonym, data) => {
305 Some(trace_context::WithContext::new((pseudonym, data), output_span))
306 }
307 }
308 }
309 .instrument(span)
310 })
311 .filter_map(move |message| {
312 let ((pseudonym, data), span) = message.into_parts();
313 let _entered = span.enter();
314 let _dispatch = tracing::debug_span!("session.dispatch").entered();
315 hopr_transport_session::counters::DISPATCH_MESSAGE_CALLS.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
316 let result = match smgr.dispatch_message(pseudonym, data) {
328 Ok(DispatchResult::Processed) => {
329 tracing::trace!("message dispatch completed");
330 None
331 }
332 Ok(DispatchResult::Unrelated(data)) => {
333 tracing::trace!("unrelated message dispatch completed");
334 Some(data)
335 }
336 Ok(DispatchResult::Dropped(reason)) => {
341 tracing::trace!(?reason, "dropped session packet");
342 None
343 }
344 Err(error) => {
345 tracing::error!(%error, "error while dispatching packet in the session manager");
346 None
347 }
348 };
349 drop(_dispatch);
350 drop(_entered);
351 async move {
352 hopr_utils::runtime::prelude::consume_budget().await;
353 result
354 }
355 .instrument(span)
356 })
357 .fold(on_incoming_data_tx, |mut tx, data| async move {
358 if tx.send(data).await.is_err() {
359 tracing::error!(
360 task = %HoprTransportProcess::SessionsManagement(0),
361 "incoming-data channel disconnected — dropping unrelated packet; \
362 HoprSocket must be consumed or drained by the caller"
363 );
364 }
365 tx
366 })
367 .await;
368}
369
370type HoprSessionManager = SessionManager<HoprMessageSender>;
372
373#[derive(Debug, Clone)]
378pub struct HoprSessionConfigurator {
379 id: SessionId,
380 smgr: std::sync::Weak<HoprSessionManager>,
382}
383
384impl HoprSessionConfigurator {
385 pub fn id(&self) -> &SessionId {
387 &self.id
388 }
389
390 pub async fn ping(&self) -> errors::Result<()> {
403 Ok(self
404 .smgr
405 .upgrade()
406 .ok_or(HoprTransportError::Other(anyhow::anyhow!("session manager is dropped")))?
407 .ping_session(&self.id)
408 .await?)
409 }
410
411 pub fn get_surb_balancer_config(&self) -> errors::Result<Option<SurbBalancerConfig>> {
417 Ok(self
418 .smgr
419 .upgrade()
420 .ok_or(HoprTransportError::Other(anyhow::anyhow!("session manager is dropped")))?
421 .get_surb_balancer_config(&self.id)?)
422 }
423
424 pub fn update_surb_balancer_config(&self, config: SurbBalancerConfig) -> errors::Result<()> {
429 Ok(self
430 .smgr
431 .upgrade()
432 .ok_or(HoprTransportError::Other(anyhow::anyhow!("session manager is dropped")))?
433 .update_surb_balancer_config(&self.id, config)?)
434 }
435
436 pub fn close(&self) -> bool {
443 match self.smgr.upgrade() {
444 Some(smgr) => smgr.close_session(&self.id),
445 None => false,
446 }
447 }
448}
449
450pub struct HoprTransport<Chain, Graph, Net> {
453 packet_key: OffchainKeypair,
454 chain_key: ChainKeypair,
455 chain_api: Chain,
456 ping: Arc<OnceLock<Pinger>>,
457 network: Arc<OnceLock<Net>>,
458 graph: Graph,
459 path_planner: PathPlanner<MemorySurbStore, Chain, HoprGraphPathSelector<Graph>>,
460 surb_round_trips: protocol::surb_telemetry::SurbRoundTripRegistry,
462 my_multiaddresses: Vec<Multiaddr>,
463 smgr: Arc<HoprSessionManager>,
464 session_telemetry_tag_allocator: Arc<dyn hopr_transport_tag_allocator::TagAllocator + Send + Sync>,
465 probing_tag_allocator: Arc<dyn hopr_transport_tag_allocator::TagAllocator + Send + Sync>,
466 counters: PeerProtocolCounterRegistry,
467 cfg: HoprProtocolConfig,
468}
469
470impl<Chain, Graph, Net> HoprTransport<Chain, Graph, Net>
471where
472 Chain: ChainReadChannelOperations
473 + ChainReadAccountOperations
474 + ChainWriteTicketOperations
475 + ChainKeyOperations
476 + ChainReadTicketOperations
477 + ChainValues
478 + Clone
479 + Send
480 + Sync
481 + 'static,
482 Graph: NetworkGraphView<NodeId = OffchainPublicKey>
483 + NetworkGraphUpdate
484 + hopr_api::graph::NetworkGraphWrite<NodeId = OffchainPublicKey>
485 + hopr_api::graph::NetworkGraphTraverse<NodeId = OffchainPublicKey>
486 + Clone
487 + Send
488 + Sync
489 + 'static,
490 <Graph as NetworkGraphView>::Observed: hopr_api::graph::traits::EdgeObservableRead + Send,
491 <Graph as hopr_api::graph::NetworkGraphTraverse>::Observed:
492 hopr_api::graph::traits::EdgeObservableRead + Send + 'static,
493 <Graph as hopr_api::graph::NetworkGraphWrite>::Observed: hopr_api::graph::traits::EdgeObservableWrite + Send,
494 Net: NetworkView + NetworkStreamControl + Clone + Send + Sync + 'static,
495{
496 pub fn new(
497 identity: (&ChainKeypair, &OffchainKeypair),
498 resolver: Chain,
499 graph: Graph,
500 my_multiaddresses: Vec<Multiaddr>,
501 cfg: HoprProtocolConfig,
502 ) -> errors::Result<Self> {
503 validator::Validate::validate(&cfg)
513 .map_err(|error| HoprTransportError::Api(format!("invalid protocol configuration: {error}")))?;
514
515 let me_offchain = *identity.1.public();
516 let planner_config = cfg.path_planner;
517 let selector = HoprGraphPathSelector::new(
518 me_offchain,
519 graph.clone(),
520 planner_config.max_cached_paths,
521 planner_config.edge_penalty,
522 planner_config.min_ack_rate,
523 planner_config.min_paths_anonymity_floor,
524 );
525
526 let tag_allocators = hopr_transport_tag_allocator::create_allocators_from_config(&cfg.session.tag_allocator)?;
527
528 let mut session_telemetry_tag_allocator = None;
529 let mut probing_tag_allocator = None;
530 for (usage, alloc) in tag_allocators {
531 match usage {
532 hopr_transport_tag_allocator::Usage::Session => {}
534 hopr_transport_tag_allocator::Usage::SessionTerminalTelemetry => {
535 session_telemetry_tag_allocator = Some(alloc)
536 }
537 hopr_transport_tag_allocator::Usage::ProvingTelemetry => probing_tag_allocator = Some(alloc),
538 }
539 }
540 let session_telemetry_tag_allocator = session_telemetry_tag_allocator
541 .ok_or_else(|| HoprTransportError::Api("session telemetry tag allocator missing".into()))?;
542 let probing_tag_allocator =
543 probing_tag_allocator.ok_or_else(|| HoprTransportError::Api("probing tag allocator missing".into()))?;
544
545 let surb_store_cfg = hopr_protocol_hopr::SurbStoreConfig {
553 pseudonyms_lifetime: std::env::var("HOPR_INTERNAL_SURB_PSEUDONYM_LIFETIME_MS")
554 .ok()
555 .and_then(|s| s.trim().parse::<u64>().ok())
556 .map(Duration::from_millis)
557 .map(|d| d.max(hopr_protocol_hopr::MINIMUM_SURB_LIFETIME))
558 .unwrap_or(cfg.packet.surb_store.pseudonyms_lifetime),
559 ..cfg.packet.surb_store
560 };
561
562 let surb_round_trips =
568 protocol::surb_telemetry::SurbRoundTripRegistry::with_budget(cfg.packet.surb_store.pending_surb_max_bytes);
569 let path_planner = PathPlanner::new(
570 me_offchain,
571 MemorySurbStore::new(surb_store_cfg),
572 resolver.clone(),
573 selector,
574 planner_config,
575 );
576
577 let smgr = Arc::new(SessionManager::new(SessionManagerConfig {
581 frame_mtu: std::env::var("HOPR_SESSION_FRAME_SIZE")
582 .ok()
583 .and_then(|s| s.parse::<usize>().ok())
584 .unwrap_or_else(|| SessionManagerConfig::default().frame_mtu)
585 .max(SESSION_MTU),
586 max_frame_timeout: std::env::var("HOPR_SESSION_FRAME_TIMEOUT_MS")
587 .ok()
588 .and_then(|s| s.parse::<u64>().ok().map(Duration::from_millis))
589 .unwrap_or_else(|| SessionManagerConfig::default().max_frame_timeout)
590 .max(Duration::from_millis(100)),
591 max_frames_behind_gap: cfg.session.max_frames_behind_gap,
592 max_buffered_segments: std::env::var("HOPR_SESSION_MAX_BUFFERED_SEGMENTS")
593 .ok()
594 .and_then(|s| s.parse::<usize>().ok())
595 .unwrap_or_else(|| SessionManagerConfig::default().max_buffered_segments),
596 initiation_timeout_base: SESSION_INITIATION_TIMEOUT_BASE,
597 idle_timeout: cfg.session.idle_timeout,
598 balancer_sampling_interval: cfg.session.balancer_sampling_interval,
599 initial_return_session_egress_rate: 10,
600 minimum_surb_buffer_duration: cfg.session.balancer_minimum_surb_buffer_duration,
601 maximum_surb_buffer_size: surb_buffer_target_ceiling(cfg.packet.surb_store.rb_capacity),
602 surb_balance_notify_period: std::env::var("HOPR_SESSION_SURB_BALANCE_NOTIFY_PERIOD_MS")
605 .ok()
606 .and_then(|s| s.parse::<u64>().ok())
607 .map(|ms| Some(Duration::from_millis(ms)))
608 .unwrap_or(cfg.session.surb_balance_notify_period),
609 surb_degraded_notify_period: surb_degraded_notify_period_override(
610 std::env::var(SURB_DEGRADED_NOTIFY_PERIOD_ENV).ok().as_deref(),
611 cfg.session.surb_degraded_notify_period,
612 ),
613 surb_idle_notify_period: cfg.session.surb_idle_notify_period,
614 surb_target_notify: cfg.session.surb_target_notify,
615 refusal_reply_budget: cfg.session.refusal_reply_budget,
616 maximum_sessions: cfg.session.maximum_managed_sessions,
617 pix_config: cfg.incoming_session_pix_config.clone(),
618 max_ssas_per_ssa_request: cfg.pix.max_ssas_per_request,
619 surb_resolution_wait: crate::path::resolve::surb_resolution_wait(cfg.packet.pipeline.surb_resolution_wait),
623 ..Default::default()
624 }));
625
626 let _ = smgr.set_surb_admission(Arc::new(StoreSurbAdmission {
631 store: path_planner.surb_store.clone(),
632 }));
633
634 if cfg.packet.surb_store.admitted_max_pseudonyms < cfg.session.maximum_managed_sessions {
640 tracing::error!(
641 admitted_max_pseudonyms = cfg.packet.surb_store.admitted_max_pseudonyms,
642 maximum_managed_sessions = cfg.session.maximum_managed_sessions,
643 "SURB store admitted capacity is smaller than the maximum number of managed sessions — sessions \
644 beyond the store's admitted capacity will lose their SURB return path"
645 );
646 }
647
648 Ok(Self {
649 packet_key: identity.1.clone(),
650 chain_key: identity.0.clone(),
651 ping: Arc::new(OnceLock::new()),
652 network: Arc::new(OnceLock::new()),
653 graph,
654 path_planner,
655 surb_round_trips,
656 my_multiaddresses,
657 smgr,
658 chain_api: resolver,
659 session_telemetry_tag_allocator,
660 probing_tag_allocator,
661 counters: PeerProtocolCounterRegistry::default(),
662 cfg,
663 })
664 }
665
666 pub fn with_observer(mut self, observer: TransportObserver) -> Self {
669 self.path_planner.configure_selector(|selector| {
670 *selector = selector.clone().with_observer(observer.clone());
671 });
672 self.path_planner = self.path_planner.with_observer(observer.clone());
673 self.surb_round_trips = self.surb_round_trips.with_observer(observer);
674 self
675 }
676
677 #[allow(clippy::too_many_arguments)]
686 pub async fn run_relay<T, TFact, Ct, PixEvt>(
687 &self,
688 cover_traffic: Ct,
689 network: Net,
690 network_process: BoxedProcessFn,
691 ticket_events: T,
692 ticket_factory: TFact,
693 exit_ack_share: Option<PixEvt>,
694 on_incoming_session: Sender<IncomingSession>,
695 on_session_admission: Option<SessionAdmissionSink>,
696 ) -> errors::Result<(
697 HoprSocket<futures::stream::BoxStream<'static, ApplicationDataIn>, HoprMessageSender>,
698 AbortableList<HoprTransportProcess>,
699 )>
700 where
701 T: futures::Sink<hopr_api::node::TicketEvent> + Clone + Send + Unpin + 'static,
702 T::Error: std::error::Error + Clone + Send,
703 Ct: ProbingTrafficGeneration + CoverTrafficGeneration + Send + Sync + 'static,
704 TFact: TicketFactory + Clone + Send + Sync + 'static,
705 PixEvt: futures::Sink<PixEvent> + Clone + Unpin + Send + 'static,
706 PixEvt::Error: std::error::Error + Clone + Sync + Send + 'static,
707 {
708 self.run_inner(
709 protocol::NodeType::Relay,
710 cover_traffic,
711 network,
712 network_process,
713 ticket_events,
714 ticket_factory,
715 exit_ack_share,
716 Some(on_incoming_session),
717 on_session_admission,
718 )
719 .await
720 }
721
722 #[allow(
730 clippy::too_many_arguments,
731 reason = "each argument is a distinct wiring point supplied by hopr-lib"
732 )]
733 pub async fn run_exit<TFact, Ct, PixEvt>(
734 &self,
735 cover_traffic: Ct,
736 network: Net,
737 network_process: BoxedProcessFn,
738 ticket_factory: TFact,
739 pix_events: Option<PixEvt>,
740 on_incoming_session: Sender<IncomingSession>,
741 on_session_admission: Option<SessionAdmissionSink>,
742 ) -> errors::Result<(
743 HoprSocket<futures::stream::BoxStream<'static, ApplicationDataIn>, HoprMessageSender>,
744 AbortableList<HoprTransportProcess>,
745 )>
746 where
747 Ct: ProbingTrafficGeneration + CoverTrafficGeneration + Send + Sync + 'static,
748 TFact: TicketFactory + Clone + Send + Sync + 'static,
749 PixEvt: futures::Sink<PixEvent> + Clone + Unpin + Send + 'static,
750 PixEvt::Error: std::error::Error + Clone + Sync + Send + 'static,
751 {
752 self.run_inner(
753 protocol::NodeType::Exit,
754 cover_traffic,
755 network,
756 network_process,
757 futures::sink::drain(),
758 ticket_factory,
759 pix_events,
760 Some(on_incoming_session),
761 on_session_admission,
762 )
763 .await
764 }
765
766 pub async fn run_entry<TFact, Ct, PixEvt>(
772 &self,
773 cover_traffic: Ct,
774 network: Net,
775 network_process: BoxedProcessFn,
776 ticket_factory: TFact,
777 pix_events: Option<PixEvt>,
778 ) -> errors::Result<(
779 HoprSocket<futures::stream::BoxStream<'static, ApplicationDataIn>, HoprMessageSender>,
780 AbortableList<HoprTransportProcess>,
781 )>
782 where
783 Ct: ProbingTrafficGeneration + CoverTrafficGeneration + Send + Sync + 'static,
784 TFact: TicketFactory + Clone + Send + Sync + 'static,
785 PixEvt: futures::Sink<PixEvent> + Clone + Unpin + Send + 'static,
786 PixEvt::Error: std::error::Error + Clone + Sync + Send + 'static,
787 {
788 self.run_inner(
789 protocol::NodeType::Entry,
790 cover_traffic,
791 network,
792 network_process,
793 futures::sink::drain(),
794 ticket_factory,
795 pix_events,
796 None,
797 None,
798 )
799 .await
800 }
801
802 #[allow(clippy::too_many_arguments)]
809 async fn run_inner<T, TFact, Ct, PixEvt>(
810 &self,
811 role: protocol::NodeType,
812 cover_traffic: Ct,
813 network: Net,
814 network_process: BoxedProcessFn,
815 ticket_events: T,
816 ticket_factory: TFact,
817 exit_ack_share: Option<PixEvt>,
818 on_incoming_session: Option<Sender<IncomingSession>>,
819 on_session_admission: Option<SessionAdmissionSink>,
820 ) -> errors::Result<(
821 HoprSocket<futures::stream::BoxStream<'static, ApplicationDataIn>, HoprMessageSender>,
822 AbortableList<HoprTransportProcess>,
823 )>
824 where
825 T: futures::Sink<hopr_api::node::TicketEvent> + Clone + Send + Unpin + 'static,
826 T::Error: std::error::Error + Clone + Send,
827 Ct: ProbingTrafficGeneration + CoverTrafficGeneration + Send + Sync + 'static,
828 TFact: TicketFactory + Clone + Send + Sync + 'static,
829 PixEvt: futures::Sink<PixEvent> + Clone + Unpin + Send + 'static,
830 PixEvt::Error: std::error::Error + Clone + Sync + Send + 'static,
831 {
832 let mut processes = AbortableList::<HoprTransportProcess>::default();
833
834 let (unresolved_routing_msg_tx, unresolved_routing_msg_rx) = bounded_sink_channel::<
835 trace_context::WithContext<(DestinationRouting, ApplicationDataOut)>,
836 >(MAXIMUM_MSG_OUTGOING_BUFFER_SIZE);
837 let unresolved_routing_msg_tx = trace_context::ContextSender::new(unresolved_routing_msg_tx);
838
839 let transport_network = network;
842 let transport_layer_process = network_process;
843
844 let msg_codec = crate::protocol::HoprBinaryCodec {};
845 let (wire_msg_tx, wire_msg_rx) =
846 protocol::stream::process_stream_protocol(msg_codec, transport_network.clone(), self.cfg.stream).await?;
847
848 let mixer_cfg = self.cfg.mixer;
853 let (mixing_channel_tx, mix_rx) = hopr_transport_mixer::create(mixer_cfg);
857 let transit_latency_cfg = self.cfg.transit_latency;
858 processes.insert(
859 HoprTransportProcess::MixerForwarder,
860 hopr_utils::spawn_as_abortable!(async move {
861 let mut mix_rx = mix_rx;
862 let mut wire_sink = wire_msg_tx;
863
864 if let Some(lat) = transit_latency_cfg {
865 #[cfg(feature = "runtime-tokio")]
871 {
872 let (tx, rx) = futures::channel::mpsc::unbounded();
873 let fan_out = async move {
874 while let Some(item) = futures::StreamExt::next(&mut mix_rx).await {
875 let mean_us = lat.mean.as_micros() as f64;
876 let std_us = lat.std_dev.as_micros() as f64;
877 let delay_us = if std_us > 0.0 {
878 use rand_distr::{Distribution, Normal};
879 Normal::new(mean_us, std_us)
880 .expect("transit latency Normal params are valid")
881 .sample(&mut rand::rng())
882 .max(0.0_f64)
883 } else {
884 mean_us.max(0.0)
885 };
886 let delay = Duration::from_micros(delay_us as u64);
887 let item_tx = tx.clone();
888 hopr_utils::runtime::prelude::spawn(async move {
889 if !delay.is_zero() {
890 futures_timer::Delay::new(delay).await;
891 }
892 let _ = item_tx.unbounded_send(item);
893 });
894 }
895 };
897 let fan_in = async move {
898 let mut rx = rx;
899 while let Some(item) = futures::StreamExt::next(&mut rx).await {
900 if wire_sink.send(item).await.is_err() {
901 tracing::error!(
902 task = %HoprTransportProcess::MixerForwarder,
903 "wire sink dropped — discarding transit-delayed packet"
904 );
905 break;
906 }
907 }
908 };
909 futures::join!(fan_out, fan_in);
910 }
911 #[cfg(not(feature = "runtime-tokio"))]
912 {
913 let _ = lat;
914 while let Some(item) = futures::StreamExt::next(&mut mix_rx).await {
915 if wire_sink.send(item).await.is_err() {
916 tracing::error!(
917 task = %HoprTransportProcess::MixerForwarder,
918 "wire sink dropped — discarding mixed packet"
919 );
920 }
921 }
922 }
923 } else {
924 while let Some(item) = futures::StreamExt::next(&mut mix_rx).await {
925 if wire_sink.send(item).await.is_err() {
926 tracing::error!(
927 task = %HoprTransportProcess::MixerForwarder,
928 "wire sink dropped — discarding mixed packet"
929 );
930 }
931 }
932 }
933
934 tracing::warn!(
935 task = %HoprTransportProcess::MixerForwarder,
936 "long-running background task finished"
937 );
938 }),
939 );
940
941 #[cfg(feature = "runtime-tokio")]
943 processes.insert(
944 HoprTransportProcess::PathRefresh,
945 hopr_utils::spawn_as_abortable!(self.path_planner.run_background_refresh()),
946 );
947
948 processes.insert(
949 HoprTransportProcess::Medium,
950 hopr_utils::spawn_as_abortable!(transport_layer_process().inspect(|_| tracing::warn!(
951 task = %HoprTransportProcess::Medium,
952 "long-running background task finished"
953 ))),
954 );
955
956 let msg_protocol_bidirectional_channel_capacity =
957 std::env::var("HOPR_INTERNAL_PROTOCOL_BIDIRECTIONAL_CHANNEL_CAPACITY")
958 .ok()
959 .and_then(|s| s.trim().parse::<usize>().ok())
960 .filter(|&c| c > 0)
961 .unwrap_or(16_384);
962
963 debug!(
964 capacity = msg_protocol_bidirectional_channel_capacity,
965 "creating protocol bidirectional channel"
966 );
967 let (tx_from_protocol, rx_from_protocol) = bounded_sink_channel::<
968 trace_context::WithContext<(HoprPseudonym, ApplicationDataIn)>,
969 >(msg_protocol_bidirectional_channel_capacity);
970 let tx_from_protocol = trace_context::ContextSender::new(tx_from_protocol);
971
972 let cover_traffic_allocated_tag = self
976 .session_telemetry_tag_allocator
977 .allocate()
978 .ok_or_else(|| HoprTransportError::Api("failed to allocate cover traffic tag".into()))?;
979 let cover_traffic_tag: Tag = cover_traffic_allocated_tag.value().into();
980
981 let rx_from_protocol = rx_from_protocol.filter_map(move |message| {
984 let _keep_alive = &cover_traffic_allocated_tag;
985 futures::future::ready((message.value.1.data.application_tag != cover_traffic_tag).then_some(message))
986 });
987
988 let cover_traffic_stream = CoverTrafficGeneration::build(&cover_traffic).filter_map(move |routing| {
990 let start =
991 hopr_api::types::crypto_random::random_integer(0, Some((RANDOM_DATA.len() - 100) as u64)) as usize;
992 let data = &RANDOM_DATA[start..start + 100];
993
994 futures::future::ready(if let Ok(data) = ApplicationData::new(cover_traffic_tag, data) {
995 Some(trace_context::WithContext::new(
996 (routing, ApplicationDataOut::with_no_packet_info(data)),
997 tracing::debug_span!(parent: None, "cover_traffic"),
998 ))
999 } else {
1000 tracing::error!("failed to construct cover traffic packet");
1001 None
1002 })
1003 });
1004
1005 let merged_unresolved_output_data =
1007 select_with_strategy(unresolved_routing_msg_rx, cover_traffic_stream, |_: &mut ()| {
1008 futures::stream::PollNext::Left
1009 });
1010
1011 let path_planner = self.path_planner.clone();
1018 let distress_threshold = self.cfg.packet.surb_store.distress_threshold;
1019 let routing_concurrency = {
1020 let avail = std::thread::available_parallelism()
1021 .ok()
1022 .map(|n| n.get())
1023 .unwrap_or(1)
1024 .max(1)
1025 * 8;
1026 self.cfg
1027 .packet
1028 .pipeline
1029 .output_concurrency
1030 .filter(|&n| n > 0)
1031 .unwrap_or(avail)
1032 };
1033 let all_resolved_external_msg_rx = crate::path::resolve::resolve_routing_stage_with_context(
1034 merged_unresolved_output_data,
1035 move |size_hint, max_surbs, unresolved| {
1036 let path_planner = path_planner.clone();
1037 async move { path_planner.resolve_routing(size_hint, max_surbs, unresolved).await }
1038 },
1039 distress_threshold,
1040 routing_concurrency,
1041 crate::path::resolve::surb_resolution_wait(self.cfg.packet.pipeline.surb_resolution_wait),
1042 );
1043
1044 let channels_dst = self
1045 .chain_api
1046 .domain_separators()
1047 .await
1048 .map_err(HoprTransportError::chain)?
1049 .channel;
1050
1051 validator::Validate::validate(&self.cfg.pix)
1065 .map_err(|error| HoprTransportError::Api(format!("invalid PIX configuration: {error}")))?;
1066 fn narrow<T: TryFrom<usize>>(value: usize, field: &str) -> errors::Result<T> {
1070 T::try_from(value).map_err(|_| HoprTransportError::Api(format!("PIX {field} out of range: {value}")))
1071 }
1072 let ssa_generator = Arc::new(
1075 hopr_protocol_pix::SsaShareGenerator::<HoprPixSpec>::try_new(hopr_protocol_pix::SsaGeneratorConfig {
1076 polynomials_per_ssa: narrow(self.cfg.pix.num_ssa_parts, "num_ssa_parts")?,
1077 threshold: narrow(self.cfg.pix.ssa_part_size, "ssa_part_size")?,
1078 surplus_shares: narrow(self.cfg.pix.surplus_shares(), "additional_shares")?,
1079 })
1080 .map_err(|error| HoprTransportError::Api(format!("invalid SSA generator configuration: {error}")))?,
1081 );
1082
1083 let surb_round_trips = self.surb_round_trips.clone();
1084
1085 let pipeline_builder = HoprPacketPipelineBuilder::new()
1086 .identity((&self.chain_key, &self.packet_key))
1087 .transport((mixing_channel_tx, wire_msg_rx))
1088 .api((tx_from_protocol, all_resolved_external_msg_rx))
1089 .surb_store(self.path_planner.surb_store.clone())
1090 .chain_api(self.chain_api.clone())
1091 .ticket_factory(ticket_factory)
1092 .ssa_generator(ssa_generator.clone())
1093 .channels_dst(channels_dst)
1094 .with_counters(self.counters.clone())
1095 .with_surb_telemetry(
1096 surb_round_trips.clone(),
1097 protocol::surb_telemetry::path_slots_of(self.graph.clone()),
1098 )
1099 .with_config(self.cfg.packet);
1100
1101 let pix_toolbox = match (role, exit_ack_share) {
1111 (protocol::NodeType::Exit, Some(ref ssa_events)) => {
1112 let (pix_tools, pipeline_builder) = wire_exit_pix(
1113 pipeline_builder,
1114 ssa_generator.clone(),
1115 ssa_reconstructor(&self.cfg.pix)?,
1116 ssa_events,
1117 self.smgr.clone(),
1118 &mut processes,
1119 );
1120
1121 let pipeline_processes = pipeline_builder.build_for_exit();
1122 processes.extend_from(pipeline_processes);
1123 Some(pix_tools)
1124 }
1125 (protocol::NodeType::Relay, None) => {
1126 let pipeline_processes = pipeline_builder.with_ticket_events(ticket_events).build_for_relay();
1130 processes.extend_from(pipeline_processes);
1131 None
1132 }
1133 (protocol::NodeType::Relay, Some(ref ssa_events)) => {
1134 let (pix_tools, pipeline_builder) = wire_exit_pix(
1138 pipeline_builder,
1139 ssa_generator.clone(),
1140 ssa_reconstructor(&self.cfg.pix)?,
1141 ssa_events,
1142 self.smgr.clone(),
1143 &mut processes,
1144 );
1145
1146 let pipeline_processes = pipeline_builder.with_ticket_events(ticket_events).build_for_relay();
1147 processes.extend_from(pipeline_processes);
1148 Some(pix_tools)
1149 }
1150 (protocol::NodeType::Entry, Some(ref ssa_events)) => {
1151 let dummy_reconstructor = ssa_reconstructor(&self.cfg.pix)?;
1161 let (pix_tools, session_pix_events) = PixToolbox::new(ssa_generator.clone(), dummy_reconstructor);
1162 processes.insert(
1163 HoprTransportProcess::PixEvents,
1164 hopr_utils::spawn_as_abortable!(
1165 session_pix_events
1173 .map(session_pix_event_to_pix_event)
1174 .map(Ok)
1175 .forward(ssa_events.clone().sink_map_err(HoprTransportError::other))
1176 ),
1177 );
1178
1179 processes.extend_from(pipeline_builder.build_for_entry());
1180 Some(pix_tools)
1181 }
1182 (_, None) => {
1183 let pipeline_processes = match role {
1185 protocol::NodeType::Relay => pipeline_builder.with_ticket_events(ticket_events).build_for_relay(),
1186 protocol::NodeType::Exit => pipeline_builder.build_for_exit(),
1187 protocol::NodeType::Entry => pipeline_builder.build_for_entry(),
1188 };
1189 processes.extend_from(pipeline_processes);
1190 None
1191 }
1192 };
1193
1194 let smgr_start_res = if role != protocol::NodeType::Entry {
1197 self.smgr.start(
1198 unresolved_routing_msg_tx.clone(),
1199 on_incoming_session.ok_or_else(|| {
1200 HoprTransportError::Api("on_incoming_session channel is required for relay/exit nodes".into())
1201 })?,
1202 pix_toolbox,
1203 on_session_admission,
1204 )
1205 } else {
1206 self.smgr.start(
1209 unresolved_routing_msg_tx.clone(),
1210 futures::sink::drain(),
1211 pix_toolbox,
1212 None,
1213 )
1214 };
1215
1216 smgr_start_res
1217 .map_err(|_| HoprTransportError::Api("failed to start session manager".into()))?
1218 .into_iter()
1219 .enumerate()
1220 .map(|(i, jh)| (HoprTransportProcess::SessionsManagement(i + 1), jh))
1221 .for_each(|(k, v)| {
1222 processes.insert(k, v);
1223 });
1224 let flush_counters = self.counters.clone();
1226 let flush_graph = self.graph.clone();
1227 let flush_me = *self.packet_key.public();
1228 let flush_interval = self.cfg.counter_flush_interval;
1229 processes.insert(
1230 HoprTransportProcess::CounterFlush,
1231 hopr_utils::spawn_as_abortable!(async move {
1232 use hopr_api::graph::traits::{EdgeObservableWrite, EdgeWeightType};
1233
1234 let ack_grace = counter_flush_ack_grace(flush_interval);
1236 let mut ticks = futures_time::stream::interval(futures_time::time::Duration::from(flush_interval));
1237 while ticks.next().await.is_some() {
1238 for (peer, num_packets, num_acks) in flush_counters.drain_settled(ack_grace).await {
1239 tracing::trace!(
1240 %peer,
1241 num_packets,
1242 num_acks,
1243 "flushing protocol conformance counters"
1244 );
1245 flush_graph.upsert_edge(&flush_me, &peer, |obs| {
1246 obs.record(EdgeWeightType::ImmediateProtocolConformance { num_packets, num_acks });
1247 });
1248 }
1249 }
1250 }),
1251 );
1252
1253 tracing::info!(?role, "starting surb round-trip flush task");
1255 let surb_flush_graph = self.graph.clone();
1256 let surb_flush_interval = self.cfg.surb_flush_interval;
1257 let surb_flush_smgr = self.smgr.clone();
1258 let surb_flush_planner = self.path_planner.clone();
1259 #[cfg(feature = "telemetry")]
1260 let surb_flush_store = self.path_planner.surb_store.clone();
1261 let latency_race_memory = self.cfg.latency_race_memory;
1262 let relayer_health_weight = self.cfg.relayer_health_weight;
1263 #[cfg(all(feature = "telemetry", not(test)))]
1264 lazy_static::initialize(&METRIC_SURB_GENERATION_BUMPS);
1265 #[cfg(all(feature = "telemetry", not(test)))]
1266 lazy_static::initialize(&METRIC_SURB_PENDING_LOST);
1267 processes.insert(
1268 HoprTransportProcess::SurbFlush,
1269 hopr_utils::spawn_as_abortable!(async move {
1270 let mut ticks = futures_time::stream::interval(futures_time::time::Duration::from(surb_flush_interval));
1271 let mut invalid = std::collections::HashMap::new();
1272 while ticks.next().await.is_some() {
1273 let now_ms = hopr_utils::platform::time::native::current_time()
1274 .as_unix_timestamp()
1275 .as_millis();
1276 #[cfg(all(feature = "telemetry", not(test)))]
1280 METRIC_SURB_PENDING_LOST.increment_by(surb_round_trips.take_pending_lost());
1281 surb_round_trips.expire_step();
1283 #[cfg(feature = "telemetry")]
1288 surb_flush_store.surbs_held();
1289
1290 protocol::surb_telemetry::flush_into(&surb_round_trips, &surb_flush_graph, now_ms);
1291 let reached = protocol::surb_telemetry::refresh_relayer_health(
1294 &surb_round_trips,
1295 &surb_flush_graph,
1296 latency_race_memory,
1297 relayer_health_weight,
1298 || surb_flush_planner.refresh_cached_paths(),
1299 )
1300 .await;
1301
1302 for pseudonym in reached {
1312 if !surb_flush_smgr.on_counterparty_surbs_wiped(&pseudonym) {
1313 surb_round_trips.forget_session(&pseudonym);
1314 continue;
1315 }
1316 let generation = surb_flush_planner.surb_store.bump_generation(&pseudonym);
1317 #[cfg(all(feature = "telemetry", not(test)))]
1318 METRIC_SURB_GENERATION_BUMPS.increment();
1319 tracing::info!(
1320 %pseudonym,
1321 generation,
1322 "dead relayer verdict: SURB generation advanced, the counterparty drops its stock on the next push"
1323 );
1324 }
1325
1326 let current = if surb_round_trips.has_write_offs() {
1334 let registry = surb_round_trips.clone();
1335 match hopr_utils::parallelize::cpu::spawn_blocking(move || registry.invalid(), "surb_invalid")
1336 .await
1337 {
1338 Ok(current) => current,
1339 Err(error) => {
1340 tracing::warn!(%error, "invalid SURB update deferred to the next flush");
1341 continue;
1342 }
1343 }
1344 } else {
1345 std::collections::HashMap::new()
1346 };
1347 for (session, (count, share)) in protocol::surb_telemetry::invalid_updates(&invalid, ¤t) {
1348 if !surb_flush_smgr.set_invalid_surbs(&session, count, share) {
1349 surb_round_trips.forget_session(&session);
1350 } else if !invalid.contains_key(&session) {
1351 tracing::info!(%session, count, share, "marking SURBs that cannot bring a reply home invalid");
1352 } else if share == 0.0 {
1353 tracing::info!(%session, "clearing invalid SURBs");
1354 }
1355 }
1356 invalid = current;
1357 }
1358 }),
1359 );
1360
1361 let manual_ping_channel_capacity = std::env::var("HOPR_INTERNAL_MANUAL_PING_CHANNEL_CAPACITY")
1363 .ok()
1364 .and_then(|s| s.trim().parse::<usize>().ok())
1365 .filter(|&c| c > 0)
1366 .unwrap_or(128);
1367 debug!(capacity = manual_ping_channel_capacity, "Creating manual ping channel");
1368 let (manual_ping_tx, manual_ping_rx_raw) =
1369 crossfire::mpsc::bounded_async::<(OffchainPublicKey, PingQueryReplier)>(manual_ping_channel_capacity);
1370 let manual_ping_rx = manual_ping_rx_raw.into_stream();
1371
1372 let probe = Probe::new(self.cfg.probe, self.probing_tag_allocator.clone());
1373
1374 let (probing_processes, probe_classifier) = probe
1375 .continuously_scan(
1376 unresolved_routing_msg_tx.clone(),
1377 manual_ping_rx,
1378 cover_traffic,
1379 self.graph.clone(),
1380 )
1381 .await;
1382
1383 processes.flat_map_extend_from(probing_processes, HoprTransportProcess::Probing);
1384
1385 self.ping
1387 .clone()
1388 .set(Pinger::new(
1389 PingConfig {
1390 timeout: self.cfg.probe.timeout,
1391 },
1392 manual_ping_tx,
1393 ))
1394 .map_err(|_| HoprTransportError::Api("must set the ticket aggregation writer only once".into()))?;
1395
1396 let (on_incoming_data_tx, on_incoming_data_rx) =
1405 bounded_sink_channel::<ApplicationDataIn>(msg_protocol_bidirectional_channel_capacity);
1406 let smgr = self.smgr.clone();
1407 let unresolved_routing_msg_tx_for_task = unresolved_routing_msg_tx.clone();
1408 processes.insert(
1409 HoprTransportProcess::SessionsManagement(0),
1410 hopr_utils::spawn_as_abortable!(async move {
1411 dispatch_incoming_messages(
1412 rx_from_protocol,
1413 probe_classifier,
1414 unresolved_routing_msg_tx_for_task,
1415 smgr,
1416 on_incoming_data_tx,
1417 )
1418 .await;
1419 tracing::warn!(
1420 task = %HoprTransportProcess::SessionsManagement(0),
1421 "long-running background task finished"
1422 );
1423 }),
1424 );
1425
1426 self.network
1428 .clone()
1429 .set(transport_network)
1430 .map_err(|_| HoprTransportError::Api("transport network viewer already set".into()))?;
1431
1432 Ok((
1433 (on_incoming_data_rx.boxed(), unresolved_routing_msg_tx).into(),
1434 processes,
1435 ))
1436 }
1437
1438 #[tracing::instrument(level = "debug", skip(self))]
1439 pub async fn ping(
1440 &self,
1441 peer: &OffchainPublicKey,
1442 ) -> errors::Result<(std::time::Duration, <Graph as NetworkGraphView>::Observed)> {
1443 let me: &OffchainPublicKey = self.packet_key.public();
1444 if peer == me {
1445 return Err(HoprTransportError::Api("ping to self does not make sense".into()));
1446 }
1447
1448 let pinger = self
1449 .ping
1450 .get()
1451 .ok_or_else(|| HoprTransportError::Api("ping processing is not yet initialized".into()))?;
1452
1453 let latency = (*pinger).ping(peer).await?;
1454
1455 if let Some(observations) = self.graph.edge(me, peer) {
1456 Ok((latency, observations))
1457 } else {
1458 Err(HoprTransportError::Api(format!(
1459 "no observations available for peer {peer}",
1460 )))
1461 }
1462 }
1463
1464 #[tracing::instrument(level = "debug", skip(self))]
1465 pub async fn new_session(
1466 &self,
1467 destination: Address,
1468 target: SessionTarget,
1469 cfg: SessionClientConfig,
1470 ) -> errors::Result<(HoprSession, HoprSessionConfigurator)> {
1471 let session = self.smgr.new_session(destination, target, cfg).await?;
1472 let id = *session.id();
1473 Ok((
1474 session,
1475 HoprSessionConfigurator {
1476 id,
1477 smgr: Arc::downgrade(&self.smgr),
1478 },
1479 ))
1480 }
1481
1482 #[tracing::instrument(level = "debug", skip(self))]
1483 pub async fn listening_multiaddresses(&self) -> Vec<Multiaddr> {
1484 self.network
1485 .get()
1486 .ok_or_else(|| HoprTransportError::Api("transport network is not yet initialized".into()))
1487 .map(|network| network.listening_as().into_iter().collect())
1488 .unwrap_or_default()
1489 }
1490
1491 #[tracing::instrument(level = "debug", skip(self))]
1492 pub fn announceable_multiaddresses(&self) -> Vec<Multiaddr> {
1493 let mut mas = self
1494 .local_multiaddresses()
1495 .into_iter()
1496 .filter(|ma| {
1497 crate::multiaddrs::is_supported(ma)
1498 && (self.cfg.transport.announce_local_addresses || is_public_address(ma))
1499 })
1500 .map(|ma| strip_p2p_protocol(&ma))
1501 .filter(|v| !v.is_empty())
1502 .collect::<Vec<_>>();
1503
1504 mas.sort_by(|l, r| {
1505 let is_left_dns = crate::multiaddrs::is_dns(l);
1506 let is_right_dns = crate::multiaddrs::is_dns(r);
1507
1508 if !(is_left_dns ^ is_right_dns) {
1509 std::cmp::Ordering::Equal
1510 } else if is_left_dns {
1511 std::cmp::Ordering::Less
1512 } else {
1513 std::cmp::Ordering::Greater
1514 }
1515 });
1516
1517 mas
1518 }
1519
1520 pub fn graph(&self) -> &Graph {
1522 &self.graph
1523 }
1524
1525 pub fn relayer_health(&self) -> std::sync::Arc<protocol::surb_telemetry::RelayerHealth> {
1527 self.surb_round_trips.relayer_health()
1528 }
1529
1530 pub fn surb_store(&self) -> &MemorySurbStore {
1535 &self.path_planner.surb_store
1536 }
1537
1538 #[tracing::instrument(level = "debug", skip(self))]
1539 pub fn local_multiaddresses(&self) -> Vec<Multiaddr> {
1540 self.network
1541 .get()
1542 .map(|network| network.listening_as().into_iter().collect())
1543 .unwrap_or_else(|| {
1544 tracing::error!("transport network is not yet initialized, cannot fetch announced multiaddresses");
1545 self.my_multiaddresses.clone()
1546 })
1547 }
1548
1549 #[tracing::instrument(level = "debug", skip(self))]
1550 pub async fn network_observed_multiaddresses(&self, peer: &OffchainPublicKey) -> Vec<Multiaddr> {
1551 match self
1552 .network
1553 .get()
1554 .ok_or_else(|| HoprTransportError::Api("transport network is not yet initialized".into()))
1555 {
1556 Ok(network) => network
1557 .multiaddress_of(&peer.into())
1558 .unwrap_or_default()
1559 .into_iter()
1560 .collect(),
1561 Err(error) => {
1562 tracing::error!(%error, "failed to get observed multiaddresses");
1563 return vec![];
1564 }
1565 }
1566 }
1567
1568 #[tracing::instrument(level = "debug", skip(self))]
1569 pub async fn network_health(&self) -> Health {
1570 self.network
1571 .get()
1572 .ok_or_else(|| HoprTransportError::Api("transport network is not yet initialized".into()))
1573 .map(|network| network.health())
1574 .unwrap_or(Health::Red)
1575 }
1576
1577 pub async fn network_connected_peers(&self) -> errors::Result<Vec<OffchainPublicKey>> {
1578 Ok(futures::stream::iter(
1579 self.network
1580 .get()
1581 .ok_or_else(|| {
1582 tracing::error!("transport network is not yet initialized");
1583 HoprTransportError::Api("transport network is not yet initialized".into())
1584 })?
1585 .connected_peers(),
1586 )
1587 .filter_map(|peer_id| async move {
1588 match peer_id_to_public_key(&peer_id) {
1589 Ok(key) => Some(key),
1590 Err(error) => {
1591 tracing::warn!(%peer_id, %error, "failed to convert PeerId to OffchainPublicKey");
1592 None
1593 }
1594 }
1595 })
1596 .collect()
1597 .await)
1598 }
1599
1600 #[tracing::instrument(level = "debug", skip(self))]
1601 pub fn network_peer_observations(&self, peer: &OffchainPublicKey) -> Option<<Graph as NetworkGraphView>::Observed> {
1602 self.graph.edge(self.packet_key.public(), peer)
1603 }
1604
1605 #[tracing::instrument(level = "debug", skip(self))]
1607 pub async fn all_network_peers(
1608 &self,
1609 minimum_score: f64,
1610 ) -> errors::Result<Vec<(OffchainPublicKey, <Graph as NetworkGraphView>::Observed)>> {
1611 let me = self.packet_key.public();
1612 Ok(self
1613 .network_connected_peers()
1614 .await?
1615 .into_iter()
1616 .filter_map(|peer| {
1617 let observation = self.graph.edge(me, &peer);
1618 if let Some(info) = observation {
1619 if info.score().is_some_and(|score| score >= minimum_score) {
1621 Some((peer, info))
1622 } else {
1623 None
1624 }
1625 } else {
1626 None
1627 }
1628 })
1629 .collect::<Vec<_>>())
1630 }
1631}
1632
1633pub(crate) fn recovered_ssa_to_pix_event(
1636 rec: &RecoveredSsa<SimplePseudonym, <HoprPixSpec as PixSpec>::AddressPrivateKey>,
1637) -> PixEvent {
1638 PixEvent::PrivateKeyRecovered(PixPrivateKeyRecovered {
1639 id: PixAddressId::new(rec.ssa_id.pseudonym(), rec.ssa_id.ssa_index()),
1640 secret: PixDepositSecret(rec.ssa.secret().clone()),
1641 })
1642}
1643
1644const PIX_EVENT_DISPATCH_CONCURRENCY: usize = 64;
1651
1652fn session_pix_event_to_pix_event(event: HoprSessionOutPixEvent) -> PixEvent {
1655 match event {
1656 HoprSessionOutPixEvent::ReadyToDeposit(AgreedSsaQuota {
1657 ssa_id,
1658 deposit_address,
1659 quota_per_ssa,
1660 deposit_data,
1661 }) => PixEvent::NewDepositAddress(PixNewDepositAddress {
1662 id: PixAddressId::new(ssa_id.pseudonym(), ssa_id.ssa_index()),
1663 address: deposit_address.into(),
1664 quota: quota_per_ssa,
1665 deposit_data,
1669 }),
1670 HoprSessionOutPixEvent::DepositNeeded(
1671 AgreedSsaQuota {
1672 ssa_id,
1673 deposit_address,
1674 quota_per_ssa,
1675 deposit_data,
1676 },
1677 notifier,
1678 ) => PixEvent::DepositAddressReceived(PixDepositAddressReceived {
1679 id: PixAddressId::new(ssa_id.pseudonym(), ssa_id.ssa_index()),
1680 address: deposit_address.into(),
1681 quota: quota_per_ssa,
1682 deposit_data,
1685 deposit_updated: notifier,
1688 }),
1689 HoprSessionOutPixEvent::DepositDataRequest(request) => PixEvent::DepositDataRequest(request),
1692 }
1693}
1694
1695async fn dispatch_share_resolution(smgr: Arc<HoprSessionManager>, resolution: HoprShareResolution) -> Option<PixEvent> {
1698 match resolution {
1699 ShareResolution::RecoveredSsa(ssa_recovery_event) => {
1700 if let Err(error) = smgr
1701 .dispatch_pix_event(HoprSessionInPixEvent::SsaRecovered(ssa_recovery_event.ssa_id))
1702 .await
1703 {
1704 tracing::error!(%error, "failed to dispatch SSA recovery PIX event to the SessionManager");
1705 }
1706 Some(recovered_ssa_to_pix_event(&ssa_recovery_event))
1707 }
1708 ShareResolution::AlmostRecoveredSsa(ssa_id) => {
1709 if let Err(error) = smgr
1710 .dispatch_pix_event(HoprSessionInPixEvent::SsaAlmostRecovered(ssa_id))
1711 .await
1712 {
1713 tracing::error!(%error, %ssa_id, "failed to dispatch early SSA recovery event to the SessionManager");
1714 }
1715 None
1716 }
1717 ShareResolution::InvalidShares {
1718 peer,
1719 ssa_id,
1720 observed_total,
1721 } => {
1722 tracing::error!(
1723 %peer, %ssa_id, observed_total,
1724 "first RP relayer sent acknowledgement indicating invalid PIX share from Entry"
1725 );
1726 if let Err(error) = smgr
1727 .dispatch_pix_event(HoprSessionInPixEvent::UnverifiableShares {
1728 ssa_id,
1729 observed_total,
1730 peer,
1731 })
1732 .await
1733 {
1734 tracing::error!(%error, %ssa_id, "failed to dispatch invalid share PIX event to the SessionManager");
1735 }
1736 None
1737 }
1738 ShareResolution::Progress(progress) => {
1742 tracing::trace!(
1743 ssa_id = %progress.ssa_id,
1744 useful_shares = progress.useful_shares,
1745 shares_seen = progress.shares_seen,
1746 target = progress.target_useful_shares,
1747 recovered_polynomials = progress.recovered_polynomials,
1748 "pix recovery progress"
1749 );
1750 if let Err(error) = smgr
1751 .dispatch_pix_event(HoprSessionInPixEvent::RecoveryProgress(progress))
1752 .await
1753 {
1754 tracing::trace!(%error, ssa_id = %progress.ssa_id, "recovery progress for an unsupervised session");
1755 }
1756 None
1757 }
1758 }
1759}
1760
1761fn ssa_reconstructor(cfg: &PixGlobalConfig) -> errors::Result<Arc<hopr_protocol_pix::SsaReconstructor<HoprPixSpec>>> {
1775 hopr_protocol_pix::SsaReconstructor::<HoprPixSpec>::try_new(cfg.reconstructor.into())
1776 .map(Arc::new)
1777 .map_err(|error| HoprTransportError::Api(format!("invalid SSA reconstructor configuration: {error}")))
1778}
1779
1780fn commitment_resolution_stream(
1786 ssa_reconstructor: Arc<hopr_protocol_pix::SsaReconstructor<HoprPixSpec>>,
1787) -> impl futures::Stream<Item = HoprShareResolution> + Send + 'static {
1788 let (ready_tx, ready_rx) = bounded_sink_channel::<()>(1);
1789 let registered = ssa_reconstructor.set_ready_resolution_notifier(move || match ready_tx.try_send(()) {
1790 Ok(()) | Err(crossfire::TrySendError::Full(())) => {}
1791 Err(crossfire::TrySendError::Disconnected(())) => {
1792 tracing::error!("PIX commitment-resolution notification stream is disconnected");
1793 }
1794 });
1795 if !registered {
1796 tracing::error!("PIX reconstructor already has a commitment-resolution notification stream");
1797 }
1798
1799 let ssa_reconstructor = Arc::downgrade(&ssa_reconstructor);
1800 ready_rx.flat_map(move |_| {
1801 futures::stream::iter(
1802 ssa_reconstructor
1803 .upgrade()
1804 .map(|reconstructor| reconstructor.take_ready_resolutions())
1805 .unwrap_or_default(),
1806 )
1807 })
1808}
1809
1810#[allow(clippy::type_complexity)]
1826fn wire_exit_pix<WIn, WOut, Chain, S, TFact, G, AppOut, AppIn, TEvt, PixEvt>(
1827 pipeline_builder: HoprPacketPipelineBuilder<WIn, WOut, Chain, S, TFact, G, AppOut, AppIn, TEvt>,
1828 ssa_generator: Arc<hopr_protocol_pix::SsaShareGenerator<HoprPixSpec>>,
1829 ssa_reconstructor: Arc<hopr_protocol_pix::SsaReconstructor<HoprPixSpec>>,
1830 ssa_events: &PixEvt,
1831 smgr: Arc<HoprSessionManager>,
1832 processes: &mut AbortableList<HoprTransportProcess>,
1833) -> (
1834 PixToolbox,
1835 HoprPacketPipelineBuilder<
1836 WIn,
1837 WOut,
1838 Chain,
1839 S,
1840 TFact,
1841 G,
1842 AppOut,
1843 AppIn,
1844 TEvt,
1845 Arc<hopr_protocol_pix::SsaReconstructor<HoprPixSpec>>,
1846 CrossfireSink<HoprShareResolution>,
1847 >,
1848)
1849where
1850 PixEvt: futures::Sink<PixEvent> + Clone + Unpin + Send + 'static,
1851 PixEvt::Error: std::error::Error + Clone + Sync + Send + 'static,
1852{
1853 let commitment_resolutions = commitment_resolution_stream(ssa_reconstructor.clone());
1854 let (pix_tools, session_pix_events) = PixToolbox::new(ssa_generator, ssa_reconstructor.clone());
1855 let (ssa_share_resolution_events_tx, ssa_share_resolution_events_rx) = bounded_sink_channel(1024);
1856 processes.insert(
1857 HoprTransportProcess::PixEvents,
1858 hopr_utils::spawn_as_abortable!(
1859 pix_event_stream(
1860 session_pix_events,
1861 ssa_share_resolution_events_rx.merge(commitment_resolutions),
1862 smgr,
1863 )
1864 .map(Ok)
1865 .forward(ssa_events.clone().sink_map_err(HoprTransportError::other))
1866 ),
1867 );
1868
1869 (
1870 pix_tools,
1871 pipeline_builder.with_exit_ack_share_processing(ssa_reconstructor, ssa_share_resolution_events_tx),
1872 )
1873}
1874
1875fn pix_event_stream(
1887 session_pix_events: impl futures::Stream<Item = HoprSessionOutPixEvent> + Send + 'static,
1888 ssa_share_resolutions: impl futures::Stream<Item = HoprShareResolution> + Send + 'static,
1889 smgr: Arc<HoprSessionManager>,
1890) -> impl futures::Stream<Item = PixEvent> + Send + 'static {
1891 session_pix_events.map(session_pix_event_to_pix_event).merge(
1892 ssa_share_resolutions
1893 .then_concurrent(
1894 move |resolution| dispatch_share_resolution(smgr.clone(), resolution),
1895 PIX_EVENT_DISPATCH_CONCURRENCY,
1896 )
1897 .filter_map(futures::future::ready),
1898 )
1899}
1900
1901impl<Chain, Graph, Net> NetworkView for HoprTransport<Chain, Graph, Net>
1906where
1907 Net: NetworkView + Send + Sync + 'static,
1908{
1909 fn listening_as(&self) -> std::collections::HashSet<Multiaddr> {
1910 self.network.get().map(|n| n.listening_as()).unwrap_or_default()
1911 }
1912
1913 fn multiaddress_of(&self, peer: &PeerId) -> Option<std::collections::HashSet<Multiaddr>> {
1914 self.network.get()?.multiaddress_of(peer)
1915 }
1916
1917 fn discovered_peers(&self) -> std::collections::HashSet<PeerId> {
1918 self.network.get().map(|n| n.discovered_peers()).unwrap_or_default()
1919 }
1920
1921 fn connected_peers(&self) -> std::collections::HashSet<PeerId> {
1922 self.network.get().map(|n| n.connected_peers()).unwrap_or_default()
1923 }
1924
1925 fn is_connected(&self, peer: &PeerId) -> bool {
1926 self.network.get().map(|n| n.is_connected(peer)).unwrap_or(false)
1927 }
1928
1929 fn health(&self) -> Health {
1930 self.network.get().map(|n| n.health()).unwrap_or(Health::Red)
1931 }
1932
1933 fn subscribe_network_events(
1934 &self,
1935 ) -> impl futures::Stream<Item = hopr_api::network::NetworkEvent> + Send + 'static {
1936 match self.network.get() {
1937 Some(n) => futures::future::Either::Left(n.subscribe_network_events()),
1938 None => futures::future::Either::Right(futures::stream::empty()),
1939 }
1940 }
1941}
1942
1943#[async_trait::async_trait]
1948impl<Chain, Graph, Net> hopr_api::node::TransportOperations for HoprTransport<Chain, Graph, Net>
1949where
1950 Chain: ChainReadChannelOperations
1951 + ChainReadAccountOperations
1952 + hopr_api::chain::ChainWriteTicketOperations
1953 + ChainKeyOperations
1954 + hopr_api::chain::ChainReadTicketOperations
1955 + ChainValues
1956 + Clone
1957 + Send
1958 + Sync
1959 + 'static,
1960 Graph: NetworkGraphView<NodeId = OffchainPublicKey>
1961 + NetworkGraphUpdate
1962 + hopr_api::graph::NetworkGraphWrite<NodeId = OffchainPublicKey>
1963 + hopr_api::graph::NetworkGraphTraverse<NodeId = OffchainPublicKey>
1964 + Clone
1965 + Send
1966 + Sync
1967 + 'static,
1968 <Graph as NetworkGraphView>::Observed: EdgeObservableRead + Send,
1969 <Graph as hopr_api::graph::NetworkGraphTraverse>::Observed: EdgeObservableRead + Send + 'static,
1970 <Graph as hopr_api::graph::NetworkGraphWrite>::Observed: hopr_api::graph::traits::EdgeObservableWrite + Send,
1971 Net: NetworkView + NetworkStreamControl + Clone + Send + Sync + 'static,
1972{
1973 type Error = errors::HoprTransportError;
1974 type Observable = <Graph as NetworkGraphView>::Observed;
1975
1976 async fn ping(&self, key: &OffchainPublicKey) -> Result<(Duration, Self::Observable), Self::Error> {
1977 self.ping(key).await
1978 }
1979
1980 async fn observed_multiaddresses(&self, key: &OffchainPublicKey) -> Vec<Multiaddr> {
1981 self.network_observed_multiaddresses(key).await
1982 }
1983}
1984
1985pub const PACKET_PAYLOAD_SIZE: usize = hopr_crypto_packet::prelude::HoprPacket::PAYLOAD_SIZE;
1987
1988#[cfg(test)]
1989mod pix_recovery_event_tests {
1990 use std::{sync::Arc, time::Duration};
1991
1992 use futures::StreamExt;
1993 use hopr_api::{
1994 node::{PixAddressId, PixEvent},
1995 types::{
1996 crypto::{
1997 keypairs::{Keypair, OffchainKeypair},
1998 types::{HalfKey, SimplePseudonym},
1999 },
2000 crypto_random::{Randomizable, random_bytes},
2001 internal::prelude::VerifiedAcknowledgement,
2002 },
2003 };
2004 use hopr_crypto_packet::HoprPixSpec;
2005 use hopr_protocol_pix::{
2006 EntryShareGenerator, ExitAcknowledgementShareProcessor, PixSpec, ShareResolution, SsaGeneratorConfig, SsaId,
2007 SsaIndex, SsaReconstructor, SsaReconstructorConfig, SsaShareGenerator, TaggedEncryptedPartialSsaShare,
2008 };
2009
2010 use super::{commitment_resolution_stream, recovered_ssa_to_pix_event};
2011
2012 #[test_log::test(tokio::test)]
2015 async fn commitment_recovery_reaches_the_private_key_event_without_a_later_ack() -> anyhow::Result<()> {
2016 let cfg = SsaGeneratorConfig {
2017 polynomials_per_ssa: 2,
2018 threshold: 2,
2019 surplus_shares: 0,
2020 };
2021 let generator = SsaShareGenerator::<HoprPixSpec>::new(cfg);
2022 let reconstructor = Arc::new(SsaReconstructor::<HoprPixSpec>::new(SsaReconstructorConfig {
2023 early_recovery_threshold: 1.0,
2024 ..Default::default()
2025 }));
2026 let mut commitment_resolutions = Box::pin(commitment_resolution_stream(reconstructor.clone()));
2027
2028 let pseudonym = SimplePseudonym::random();
2029 let peer = OffchainKeypair::random();
2030 let ssa_id = SsaId::new(pseudonym, SsaIndex::MIN);
2031
2032 let client = generator.new_ssa_commitment(&pseudonym, SsaIndex::MIN)?;
2033 let server_commitment = reconstructor.new_exit_commitment(
2034 ssa_id,
2035 hopr_protocol_pix::PixParams::try_new_for::<HoprPixSpec>(2, 2, 0)?,
2036 )?;
2037 let expected_addr = HoprPixSpec::group_to_deposit_address(client.ssa_commitment + server_commitment)
2038 .ok_or_else(|| anyhow::anyhow!("deposit address"))?;
2039
2040 let mut acks = Vec::new();
2043 while let Some((msg, share)) = {
2044 let msg = random_bytes::<20>();
2045 generator.next_share(&pseudonym, &msg).map(|v| v.map(|u| (msg, u)))
2046 }? {
2047 let ack = HalfKey::random();
2048 let enc = share.share.encrypt(&share.id, &ack)?;
2049 reconstructor.insert_encrypted_share(
2050 peer.public(),
2051 ack.to_challenge()?,
2052 TaggedEncryptedPartialSsaShare::new(pseudonym, &msg, enc)?,
2053 )?;
2054 acks.push(VerifiedAcknowledgement::new(ack, &peer).leak());
2055 }
2056
2057 assert!(
2058 reconstructor.acknowledge_shares(*peer.public(), acks)?.is_empty(),
2059 "acknowledgements must remain deferred until the commitment installs their verifiers"
2060 );
2061
2062 client.process_into_reconstructor(reconstructor.as_ref())?;
2065
2066 let progress = tokio::time::timeout(Duration::from_secs(1), commitment_resolutions.next())
2067 .await
2068 .map_err(|_| anyhow::anyhow!("timed out waiting for commitment-side recovery progress"))?
2069 .ok_or_else(|| anyhow::anyhow!("commitment resolution stream ended before reporting progress"))?;
2070 assert!(matches!(progress, ShareResolution::Progress(_)));
2071
2072 let recovered = tokio::time::timeout(Duration::from_secs(1), commitment_resolutions.next())
2073 .await
2074 .map_err(|_| anyhow::anyhow!("timed out waiting for commitment-side SSA recovery"))?
2075 .ok_or_else(|| anyhow::anyhow!("commitment resolution stream ended before SSA recovery"))?;
2076 let rec = recovered
2077 .try_as_recovered_ssa()
2078 .ok_or_else(|| anyhow::anyhow!("expected a RecoveredSsa resolution"))?;
2079
2080 assert!(futures::poll!(commitment_resolutions.next()).is_pending());
2083
2084 assert_eq!(<HoprPixSpec as PixSpec>::DepositAddress::from(&rec.ssa), expected_addr);
2085
2086 let PixEvent::PrivateKeyRecovered(pk) = recovered_ssa_to_pix_event(&rec) else {
2087 anyhow::bail!("expected PrivateKeyRecovered");
2088 };
2089
2090 assert_eq!(pk.id, PixAddressId::new(&pseudonym, ssa_id.ssa_index()));
2091 assert_eq!(pk.secret.0.as_ref(), rec.ssa.secret().as_ref());
2092
2093 Ok(())
2094 }
2095}
2096
2097#[cfg(test)]
2098mod tests {
2099 mod dispatch;
2100
2101 pub(crate) mod support {
2102 use std::{collections::BTreeMap, io::Write, sync::Arc};
2108
2109 use parking_lot::Mutex;
2110 use test_log::tracing_subscriber::{self as subscriber, Layer, layer::SubscriberExt, registry::LookupSpan};
2111 use tracing::{Subscriber, field::Visit};
2112
2113 #[derive(Default)]
2114 struct Fields(BTreeMap<String, String>);
2115
2116 impl Visit for Fields {
2117 fn record_debug(&mut self, field: &tracing::field::Field, value: &dyn std::fmt::Debug) {
2118 self.0.insert(field.name().into(), format!("{value:?}"));
2119 }
2120
2121 fn record_str(&mut self, field: &tracing::field::Field, value: &str) {
2122 self.0.insert(field.name().into(), value.into());
2123 }
2124 }
2125
2126 pub(crate) struct Record {
2127 pub fields: BTreeMap<String, String>,
2128 pub ancestry: Vec<&'static str>,
2129 }
2130
2131 #[derive(Clone, Default)]
2132 pub(crate) struct Logs {
2133 events: Arc<Mutex<Vec<Record>>>,
2134 output: Arc<Mutex<Vec<u8>>>,
2135 causes: Arc<Mutex<Vec<(&'static str, &'static str)>>>,
2136 }
2137
2138 impl Logs {
2139 pub fn with_cpu_subscriber<F>(
2140 &self,
2141 subscriber: impl Subscriber + Send + Sync + 'static,
2142 future: F,
2143 ) -> anyhow::Result<F::Output>
2144 where
2145 F: std::future::Future + Send,
2146 F::Output: Send,
2147 {
2148 use tracing::instrument::WithSubscriber;
2149
2150 let dispatch = tracing::Dispatch::new(subscriber);
2151 let worker_dispatch = dispatch.clone();
2152 let pool = hopr_utils::parallelize::cpu::rayon::ThreadPoolBuilder::new()
2155 .num_threads(2)
2156 .spawn_handler(move |thread| {
2157 let dispatch = worker_dispatch.clone();
2158 std::thread::Builder::new()
2159 .spawn(move || tracing::dispatcher::with_default(&dispatch, || thread.run()))
2160 .map(|_| ())
2161 })
2162 .build()?;
2163 let runtime = tokio::runtime::Handle::current();
2164 Ok(tokio::task::block_in_place(|| {
2165 pool.install(|| runtime.block_on(future.with_subscriber(dispatch)))
2166 }))
2167 }
2168
2169 pub fn subscriber(&self, level: tracing::Level) -> impl Subscriber + Send + Sync + 'static {
2170 self.subscriber_disabling_spans(level, &[])
2171 }
2172
2173 pub fn subscriber_disabling_spans(
2174 &self,
2175 level: tracing::Level,
2176 disabled_spans: &'static [&'static str],
2177 ) -> impl Subscriber + Send + Sync + 'static {
2178 let output = self.output.clone();
2179 subscriber::registry()
2180 .with(self.clone())
2181 .with(
2182 subscriber::fmt::layer()
2183 .with_ansi(false)
2184 .without_time()
2185 .with_writer(move || Writer(output.clone())),
2186 )
2187 .with(subscriber::filter::dynamic_filter_fn(move |metadata, _| {
2190 *metadata.level() <= level && !(metadata.is_span() && disabled_spans.contains(&metadata.name()))
2191 }))
2192 }
2193
2194 pub fn records(&self, message: &str) -> Vec<Record> {
2195 self.events
2196 .lock()
2197 .iter()
2198 .filter(|event| event.fields.get("message").is_some_and(|value| value == message))
2199 .map(|event| Record {
2200 fields: event.fields.clone(),
2201 ancestry: event.ancestry.clone(),
2202 })
2203 .collect()
2204 }
2205
2206 pub fn output(&self) -> String {
2207 String::from_utf8_lossy(&self.output.lock()).into_owned()
2208 }
2209
2210 pub fn causes(&self) -> Vec<(&'static str, &'static str)> {
2211 self.causes.lock().clone()
2212 }
2213 }
2214
2215 impl<S: Subscriber + for<'a> LookupSpan<'a>> Layer<S> for Logs {
2216 fn on_follows_from(
2217 &self,
2218 span: &tracing::span::Id,
2219 follows: &tracing::span::Id,
2220 ctx: subscriber::layer::Context<'_, S>,
2221 ) {
2222 if let (Some(span), Some(cause)) = (ctx.span(span), ctx.span(follows)) {
2223 self.causes.lock().push((span.name(), cause.name()));
2224 }
2225 }
2226
2227 fn on_event(&self, event: &tracing::Event<'_>, ctx: subscriber::layer::Context<'_, S>) {
2228 let mut fields = Fields::default();
2229 event.record(&mut fields);
2230 let ancestry = ctx
2231 .event_scope(event)
2232 .map_or_else(Vec::new, |scope| scope.from_root().map(|span| span.name()).collect());
2233 self.events.lock().push(Record {
2234 fields: fields.0,
2235 ancestry,
2236 });
2237 }
2238 }
2239
2240 struct Writer(Arc<Mutex<Vec<u8>>>);
2241
2242 impl Write for Writer {
2243 fn write(&mut self, bytes: &[u8]) -> std::io::Result<usize> {
2244 self.0.lock().extend_from_slice(bytes);
2245 Ok(bytes.len())
2246 }
2247
2248 fn flush(&mut self) -> std::io::Result<()> {
2249 Ok(())
2250 }
2251 }
2252 }
2253
2254 use rstest::rstest;
2255
2256 use super::*;
2257
2258 #[rstest]
2259 #[case::unset(None, Some(Duration::from_secs(1)), Some(Duration::from_secs(1)))]
2260 #[case::override_wins(Some("2500"), Some(Duration::from_secs(1)), Some(Duration::from_millis(2500)))]
2261 #[case::override_enables_a_disabled_period(Some("3000"), None, Some(Duration::from_secs(3)))]
2262 #[case::unparsable_falls_back(Some("soon"), Some(Duration::from_secs(1)), Some(Duration::from_secs(1)))]
2263 #[case::unparsable_keeps_disabled(Some(""), None, None)]
2264 fn the_degraded_notify_period_env_override_wins_when_it_parses(
2265 #[case] raw: Option<&str>,
2266 #[case] configured: Option<Duration>,
2267 #[case] expected: Option<Duration>,
2268 ) {
2269 assert_eq!(expected, surb_degraded_notify_period_override(raw, configured));
2270 }
2271
2272 #[test]
2278 fn surb_admission_raise_target_delegates_to_the_store() -> anyhow::Result<()> {
2279 use anyhow::Context;
2280 use hopr_api::types::{crypto::crypto_traits::Randomizable, internal::prelude::HoprPseudonym};
2281 use hopr_protocol_hopr::SurbStoreConfig;
2282
2283 use super::{MemorySurbStore, StoreSurbAdmission, SurbAdmissionControl};
2284
2285 let admission = StoreSurbAdmission {
2286 store: MemorySurbStore::new(SurbStoreConfig::default()),
2287 };
2288 let pseudonym: super::SessionId = HoprPseudonym::random();
2289
2290 let token = admission.admit(&pseudonym, 688);
2292 let ping_ceiling = admission
2293 .store
2294 .admitted_ring_ceiling(&pseudonym)
2295 .context("the admission must have installed a ring")?;
2296 assert_eq!(1_032, ping_ceiling, "fixture: 688 with 50% headroom");
2297
2298 admission.raise_target(&pseudonym, token, 6_887);
2299 assert!(
2300 admission.store.admitted_ring_ceiling(&pseudonym).unwrap_or(0) > ping_ceiling,
2301 "a raise must widen the ring the token names"
2302 );
2303
2304 let successor = admission.admit(&pseudonym, 64);
2306 let successor_ceiling = admission.store.admitted_ring_ceiling(&pseudonym).unwrap_or(0);
2307 admission.raise_target(&pseudonym, token, 9_999);
2308 assert_eq!(
2309 successor_ceiling,
2310 admission.store.admitted_ring_ceiling(&pseudonym).unwrap_or(0),
2311 "a stale token must not widen the successor's ring"
2312 );
2313 assert_ne!(token, successor);
2314
2315 admission.retire(&pseudonym, successor);
2317 assert!(
2318 admission.store.admitted_ring_ceiling(&pseudonym).is_none(),
2319 "the retire must release the ring"
2320 );
2321
2322 Ok(())
2323 }
2324
2325 #[rstest]
2337 #[case::the_smallest_allowed(1_024)]
2338 #[case::a_round_one(30_000)]
2339 #[case::the_default(hopr_protocol_hopr::SurbStoreConfig::default().rb_capacity)]
2340 #[test]
2341 fn announcing_the_target_ceiling_admits_a_ring_of_the_full_capacity(
2342 #[case] rb_capacity: usize,
2343 ) -> anyhow::Result<()> {
2344 use anyhow::Context;
2345 use hopr_api::types::{crypto::crypto_traits::Randomizable, internal::prelude::HoprPseudonym};
2346 use hopr_protocol_hopr::SurbStoreConfig;
2347
2348 use super::{MemorySurbStore, StoreSurbAdmission, SurbAdmissionControl, surb_buffer_target_ceiling};
2349
2350 let admission = StoreSurbAdmission {
2351 store: MemorySurbStore::new(SurbStoreConfig {
2352 rb_capacity,
2353 ..Default::default()
2354 }),
2355 };
2356 let pseudonym: super::SessionId = HoprPseudonym::random();
2357
2358 admission.admit(&pseudonym, surb_buffer_target_ceiling(rb_capacity));
2359 let ring = admission
2360 .store
2361 .admitted_ring_ceiling(&pseudonym)
2362 .context("the admission must have installed a ring")?;
2363
2364 assert!(
2365 ring <= rb_capacity && rb_capacity - ring <= 1,
2366 "a Session announcing the target ceiling must get the whole {rb_capacity}-SURB capacity (to within a SURB \
2367 of rounding), got a ring of {ring}"
2368 );
2369 Ok(())
2370 }
2371}