Skip to main content

hopr_transport/
lib.rs

1//! The crate aggregates and composes individual transport level objects and functionality
2//! into a unified [`crate::HoprTransport`] object with the goal of isolating the transport layer
3//! and defining a fully specified transport API.
4//!
5//! See also the `hopr_protocol_start` crate for details on Start sub-protocol which initiates a Session.
6//!
7//! As such, the transport layer components should be only those that are directly necessary to:
8//!
9//! 1. send and receive a packet, acknowledgement or ticket aggregation request
10//! 2. send and receive a network telemetry request
11//! 3. automate transport level processes
12//! 4. algorithms associated with the transport layer operational management
13//! 5. interface specifications to allow modular behavioral extensions
14
15/// Configuration of the [crate::HoprTransport].
16pub mod config;
17/// Constants used and exposed by the crate.
18pub mod constants;
19/// Errors used by the crate.
20pub mod errors;
21pub mod observer;
22/// Graph-based path planning for the HOPR transport layer.
23pub mod path;
24/// Transport binary protocol layer (codec, pipeline, heartbeat, stream).
25pub mod protocol;
26/// Test utilities: emulated peer wiring, stub chain API, shared keypair/payload fixtures.
27/// Enabled by the `testing` feature; every item is a zero-cost no-op stub when absent.
28#[cfg(feature = "testing")]
29pub mod testing;
30
31mod multiaddrs;
32/// Context propagation for locally originated packets.
33pub mod trace_context;
34
35/// Outgoing application sender retaining the originating tracing context.
36pub 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};
72/// Re-exported so a consumer can name `<HoprPixSpec as PixSpec>::DepositAddress` and assert at
73/// compile time that it is the variant it can actually settle. Which instantiation is in play is
74/// a feature-graph outcome rather than a local decision, and getting it wrong is otherwise silent
75/// until deposits stop happening at runtime.
76pub use hopr_protocol_pix::PixSpec;
77pub use hopr_protocol_pix::RecoveredSsa;
78use hopr_protocol_pix::ShareResolution;
79/// Packet mixing API, re-exported whole so a consumer of the transport object can configure and
80/// inspect the mixer without pinning `hopr-transport-mixer` itself.
81///
82/// Every engine feature is already enabled by this crate's dependency declaration, so `create`,
83/// `poisson_channel`, `channel` and `MixerSink` are reached through this module.
84pub 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
165/// Fraction of the SURB ring buffer a Session's balancer target may occupy.
166///
167/// The remainder is headroom for balancer overshoot. The target used to be the ring buffer capacity
168/// itself, which left none: a Session whose buffer sat at target — the normal state when Entry → Exit
169/// traffic far exceeds the reverse, since the Exit then drains almost nothing — turned every
170/// overshot SURB into an immediate eviction of the oldest entry. Under PIX that is a lost SSA share,
171/// not just a lost SURB, because a share reaches the reconstructor only when its SURB is used.
172const SURB_BUFFER_TARGET_NUMERATOR: usize = 2;
173const SURB_BUFFER_TARGET_DENOMINATOR: usize = 3;
174
175/// Largest SURB buffer target a Session may request, given the ring buffer capacity backing it.
176///
177/// Kept strictly below `rb_capacity` so the balancer has somewhere to overshoot into before the
178/// ring buffer starts overwriting. See [`SURB_BUFFER_TARGET_NUMERATOR`].
179const fn surb_buffer_target_ceiling(rb_capacity: usize) -> usize {
180    // Saturating rather than wrapping: an operator-supplied capacity is only range-validated at the
181    // low end, and the multiplication would otherwise overflow on an absurd value.
182    rb_capacity.saturating_mul(SURB_BUFFER_TARGET_NUMERATOR) / SURB_BUFFER_TARGET_DENOMINATOR
183}
184
185/// Bridges the [`SessionManager`]'s admission seam onto the packet pipeline's SURB store.
186///
187/// This is the only crate that sees both sides — the session crate cannot name
188/// `hopr-protocol-hopr`, and the store cannot name the session crate — so the adapter has to live
189/// here, which is also why it is constructed in [`HoprTransport::new`] rather than inside either
190/// component. It is pure delegation: the manager already knows when a Session becomes established
191/// and when it is torn down, and the store already owns the sizing and the idempotency, so the
192/// adapter adds no policy of its own.
193struct 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
212/// Share of the counter flush interval a conformance report waits for its packets' acknowledgments.
213///
214/// See [`PeerProtocolCounterRegistry::drain_settled`] for why it waits at all. A third of the
215/// interval is 5 s at the 15 s default: it outlasts the multi-second acknowledgment lag of a cold
216/// burst measured in hoprnet#8484, and leaves every report a full interval's worth of sends.
217const COUNTER_FLUSH_ACK_GRACE_DIVISOR: u32 = 3;
218
219/// How long each protocol-conformance report waits for acknowledgments of the packets it counts.
220fn counter_flush_ack_grace(flush_interval: Duration) -> Duration {
221    flush_interval / COUNTER_FLUSH_ACK_GRACE_DIVISOR
222}
223
224/// The environment variable that overrides `session.surb_degraded_notify_period`, in milliseconds.
225const SURB_DEGRADED_NOTIFY_PERIOD_ENV: &str = "HOPR_SESSION_SURB_DEGRADED_NOTIFY_PERIOD_MS";
226
227/// The Exit's degraded SURB notification period: `raw` (the environment override) when it parses as
228/// milliseconds, the configured one otherwise.
229///
230/// The floor is `MIN_SURB_BUFFER_NOTIFICATION_PERIOD`, enforced once in `SessionManager::new`. A period at or
231/// above the normal one reports no faster, and `spawn_exit_keep_alive` treats it as disabled rather than
232/// switching between two equal cadences.
233fn 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
239/// Reads the packet key out of an Ed25519 [`PeerId`]'s multihash.
240///
241/// This used to be CPU-intensive - it decompressed the curve point - and was served from a
242/// process-wide cache. The compact [`OffchainPublicKey`] carries the compressed encoding as-is,
243/// so the conversion is now a length check and a copy, and caching it would cost more than it
244/// saves.
245pub 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    /// Periodically reports SURB round-trip counts into the network graph.
274    SurbFlush,
275    #[strum(to_string = "mixer→wire forwarder")]
276    MixerForwarder,
277    #[cfg(feature = "capture")]
278    #[strum(to_string = "packet capture")]
279    Capture,
280}
281
282/// Classifies probes and dispatches session traffic while retaining each packet's context.
283/// Unrelated data reaches the application sink; a closed sink does not stop ingress.
284async 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            // `dispatch_message` is synchronous and lock-free (moka::sync + crossfire
317            // try_send); it never blocks. However, the crossfire stream that feeds
318            // this loop does not participate in tokio's cooperative budget, so
319            // `future::ready` — which is always Poll::Ready — would let this task
320            // monopolize its worker thread under a saturated inbound queue (Processed
321            // items are filtered to None before the fold's tx.send().await, the only
322            // other suspension point on the hot path). Calling consume_budget() here
323            // integrates this loop into tokio's coop scheduler: it is a cheap
324            // thread-local decrement on the fast path and only actually yields
325            // (~every 128 polls) when the budget is exhausted, giving co-located
326            // tasks (including the SPHINX-crypto Rayon pipeline) a chance to run.
327            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                // Benign drop: the session's sink has closed, its inbox is momentarily
337                // full (backpressure), or the session is already deregistered. Counted
338                // in the session manager and logged quietly here so a departing
339                // counterparty cannot spam ERROR once per in-flight packet.
340                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
370/// HOPR protocol specific instantiation of the SessionManager.
371type HoprSessionManager = SessionManager<HoprMessageSender>;
372
373/// Allows configuration of one specific [`HoprSession`].
374///
375/// The configurator does not prevent the Session from being closed
376/// or the Session manager from being dropped.
377#[derive(Debug, Clone)]
378pub struct HoprSessionConfigurator {
379    id: SessionId,
380    // Makes sure configurator does not extend lifetime of the SessionManager.
381    smgr: std::sync::Weak<HoprSessionManager>,
382}
383
384impl HoprSessionConfigurator {
385    /// [`SessionId`] of the session this object can configure.
386    pub fn id(&self) -> &SessionId {
387        &self.id
388    }
389
390    /// Sends a Session Keep-Alive packet over the Session.
391    ///
392    /// NOTE: This usually carries at least 2 SURBs on the HOPR protocol level and can be
393    /// used for manual SURB balancing.
394    ///
395    /// NOTE: The keep-alive is marked as a manual ping, so the other side does not take it for a sign
396    /// that this Session runs a SURB balancer: an Exit that receives it does not start its SURB-level
397    /// reports or the reserve it keeps for them. A Session without a SURB balancer can ping without
398    /// being sent reports it does not read. An Exit that predates the mark still starts them.
399    ///
400    /// NOTE: This operation only sends the Session Keep-Alive packet and **DOES NOT** guarantee the other side
401    /// has received it.
402    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    /// Gets the configuration of the SURB balancer.
412    ///
413    /// Returns an error if the Session is closed, the Session manager is gone.
414    ///
415    /// Returns `Ok(None)` if the Session has been created without a SURB balancer.
416    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    /// Updates the configuration of the SURB balancer.
425    ///
426    /// Returns an error if the Session is closed, the Session manager is gone, or the
427    /// Session has been created without a SURB balancer.
428    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    /// Explicitly closes the underlying Session in the [`SessionManager`].
437    ///
438    /// Returns `true` if the session was found and closed, `false` if it was
439    /// already gone (or the manager is dropped). Frees the per-session state
440    /// (frame reassembly buffers, control channels, …) immediately rather than
441    /// waiting for the manager's idle-timeout eviction.
442    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
450/// Interface into the physical transport mechanism allowing all off-chain HOPR-related tasks on
451/// the transport.
452pub 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-trip counters and per-relayer health, shared with the planner.
461    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        // Validated at the constructor boundary, because this is the boundary. The shared node
504        // builder does validate before all four of its build methods reach here, but this function is
505        // `pub`, and a direct caller then skips every relational check on the way in — including
506        // `validate_pix_supervision_pairing`, which is a schema-level validator on
507        // `HoprProtocolConfig` and so is not reached by validating any single field.
508        //
509        // `run_inner` validates `self.cfg.pix` alone, which is the narrower of the two: it cannot see
510        // the supervisor-against-reconstructor pairing, and it runs at Session establishment rather
511        // than at construction — long after a caller could have been told.
512        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                // TODO: cleanup of Session tag allocators needed * (#8199)
533                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        // A pseudonym's SURB ring buffer is dropped once no SURBs have arrived for
546        // `pseudonyms_lifetime` (600 s by default), which is the point at which that pseudonym's
547        // return path becomes permanently unresolvable. Nothing else in the node can be made to
548        // reach that state on a test timescale — the Session slot is evicted for idleness long
549        // before it — so without a way to shorten this timer, the behaviour past it is not
550        // observable end-to-end at all. Floored at the same `MINIMUM_SURB_LIFETIME` the config
551        // validator enforces, so this cannot reach a value the config file could not also express.
552        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        // The race telemetry reads a reply's lateness by the SURB a replier spends first, which FIFO, the
563        // only pop order, makes the older of the two.
564        //
565        // The pending maps are bounded by the byte budget the operator sets, per map, so the pair's
566        // worst case is twice it; see `SurbRoundTripRegistry::with_budget`.
567        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        // Bound before the struct literal rather than inside it so `set_surb_admission` below can
578        // reach the manager: the seam depends on `path_planner`, which does not exist inside the
579        // literal, and `HoprTransport` has no way to reach its own `smgr` mid-construction.
580        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            // The lower bound is enforced once in `SessionManager::new` via
603            // `MIN_SURB_BUFFER_NOTIFICATION_PERIOD`; don't duplicate that floor as a literal here.
604            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            // Threaded rather than re-derived in the session crate: the deferred retire of a closing
620            // Session's SURB admission has to wait out this window, and it is the operator's own
621            // pipeline setting here that decides how long that is.
622            surb_resolution_wait: crate::path::resolve::surb_resolution_wait(cfg.packet.pipeline.surb_resolution_wait),
623            ..Default::default()
624        }));
625
626        // Wire the SURB-store admission seam: without it, every Session's SURBs — established or
627        // not — land in the store's quarantine class and are capped and expired like any
628        // unauthenticated peer's (hoprnet#8515). The `let _ =` matches the seam's contract: the
629        // manager is freshly constructed here, so nothing can have set it yet.
630        let _ = smgr.set_surb_admission(Arc::new(StoreSurbAdmission {
631            store: path_planner.surb_store.clone(),
632        }));
633
634        // The store's admitted class cannot see the session config, so the invariant that it must
635        // hold every Session that can be managed at once is checked here, where both figures are in
636        // scope. Violating it does not break the node — quarantine still resolves the SURBs — but
637        // the excess Sessions would silently fall back to the 16-SURB cap, so it is surfaced loudly
638        // rather than left to be diagnosed from eviction metrics later.
639        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    /// Attach a path, search and SURB observer before starting transport.
667    /// Cloned planner state is detached so existing users keep their observer.
668    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    /// Execute all processes of the [`HoprTransport`] object as a **Relay** node.
678    ///
679    /// Relay nodes run the full packet pipeline including incoming ticket/acknowledgement
680    /// processing and require a [`futures::Sink`] for ticket events as well as an
681    /// `on_incoming_session` channel from the SessionManager (they can accept incoming sessions).
682    ///
683    /// The Relay node may also opt in to allow itself to use the PIX protocol by setting
684    /// the `exit_ack_share` if it wishes to also act as an Exit node.
685    #[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    /// Execute all processes of the [`HoprTransport`] object as an **Exit** (destination) node.
723    ///
724    /// Exit nodes do not process tickets but keep the incoming acknowledgement
725    /// pipeline running and can accept incoming sessions via SessionManager.
726    ///
727    /// The Exit nodes also work with the PIX protocol, so they process incoming acknowledgements
728    /// to decrypt PIX shares.
729    #[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    /// Execute all processes of the [`HoprTransport`] object as an **Entry** (source) node.
767    ///
768    /// Entry nodes do not process tickets, do not start the incoming acknowledgement
769    /// pipeline, and do not accept incoming sessions — therefore, they require neither a
770    /// `ticket_events` sink nor an `on_incoming_session` channel.
771    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    /// Internal worker driving all node-type variants of `HoprTransport::run_*`.
803    ///
804    /// Branches on `role`:
805    /// - [`protocol::NodeType::Relay`]: full packet pipeline + SessionManager.
806    /// - [`protocol::NodeType::Exit`]: ack-drain pipeline + incoming Sessions.
807    /// - [`protocol::NodeType::Entry`]: no ack pipeline, no incoming Sessions.
808    #[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        // -- transport medium
840
841        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        // Shared mixing channel: all per-destination clones of `mixing_channel_tx` push into one
849        // heap, so cross-destination packets are mixed together rather than each destination
850        // getting its own independent delay queue. The single forwarder task owns the receiver
851        // (and therefore the heap timer) — no per-clone waker coordination is needed.
852        let mixer_cfg = self.cfg.mixer;
853        // The mixer implementation is selected at runtime from `mixer_cfg.mixer_type`; every
854        // engine exposes the same `Sink`/`Stream` surface, so the pipeline and forwarder below
855        // are agnostic to which one runs.
856        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                    // Concurrent transit-latency fan-out: spawn one short-lived task per
866                    // packet so each packet ages through its own ~mean delay independently.
867                    // A burst of N packets at mean=50 ms takes ~50 ms total, not N×50 ms.
868                    //
869                    // Without a tokio runtime the latency is silently skipped (pass-through).
870                    #[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                            // `tx` drops here; the channel closes once all per-packet tasks send
896                        };
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        // -- path cache background refresh (only when tokio runtime is available)
942        #[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        // === START === cover traffic control
973        // Allocate a cover traffic tag from the session telemetry partition to avoid
974        // collisions with session and probing tags.
975        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        // filter out the known cover traffic not to lose processing time with it
982        // The allocated tag is moved into the closure to keep it alive for the transport lifetime.
983        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        // prepare a cover traffic stream
989        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        // merge cover traffic with other outgoing data
1006        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        // === END === cover traffic control
1012
1013        // We have to resolve DestinationRouting -> ResolvedTransportRouting before
1014        // sending the external packets to the transport pipeline. Concurrency matches
1015        // the encoder stage (output_concurrency) to avoid head-of-line blocking on
1016        // cache-miss path lookups.
1017        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        // The SSA generator is dimensioned from the global PIX config, and that is the only place
1052        // the dimensions come from: `new_session` reads them straight off this generator to build
1053        // what it announces, so every PIX Session on this node is established at exactly these
1054        // values and one generator suffices. `handle_ssa_request` (SessionManager) then holds the
1055        // Exit to them, rejecting a negotiated quota that differs before any client commitments are
1056        // generated. `new_exit_commitment` itself adds no range check — a `PixParams` can only
1057        // come from `try_new`, which is what bounds polys_per_ssa and shares_per_poly.
1058        //
1059        // Validated here rather than left to the constructor: `PixGlobalConfig` carries more than
1060        // the three fields `SsaGeneratorConfig` covers, and this used to be a SAFETY comment
1061        // asserting that it had already been validated "before this code runs" via
1062        // `#[validate(nested)]` — but nothing in this crate calls `validate()`, so the guarantee
1063        // rested entirely on every caller remembering to.
1064        validator::Validate::validate(&self.cfg.pix)
1065            .map_err(|error| HoprTransportError::Api(format!("invalid PIX configuration: {error}")))?;
1066        // Checked rather than `as`-cast: the validation above already bounds all three, but a
1067        // truncating cast would turn a future widening of any of those ranges into a silently
1068        // wrong-but-valid-looking dimension rather than a startup error.
1069        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        // `try_new`, not `new`: the dimensions come from operator configuration, so a range
1073        // violation is a startup error to report rather than a panic to take down the node.
1074        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        // ── PixToolbox for the SessionManager ────────────────────────────
1102        // The SessionManager needs a PixToolbox on all node types to handle
1103        // PIX protocol messages (SsaRequest on Entry, SsaCommit on Exit).
1104        // Only Exit nodes construct an SsaReconstructor and wire SSA recovery
1105        // events back through the packet pipeline. Relay nodes do NOT
1106        // participate in PIX share processing at the pipeline level.
1107        // Entry nodes get a bare-bones PixToolbox (share_generator + dummy
1108        // reconstructor) to handle SsaRequest, but do not use the
1109        // reconstructor for SSA recovery.
1110        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                // Pure relay nodes do not participate in PIX — do not create a
1127                // PixToolbox so the SessionManager rejects UsePIX
1128                // pre-emptively during session initiation.
1129                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                // A relay that also acts as an Exit (has exit_ack_share) needs
1135                // a full PixToolbox to handle the PIX handshake — the same wiring as the
1136                // `(Exit, Some)` arm above, differing only in the terminal below.
1137                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                // Entry nodes need a bare-bones PixToolbox (share_generator only)
1152                // to handle incoming SsaRequest messages from the Exit.
1153                // No SSA reconstruction needed on Entry — forward events to the
1154                // PIX event broadcast so subscribers (e.g. tests) see them.
1155                // Configured like any other, not left on the defaults: this reconstructor is called
1156                // "dummy" because Entry does not reconstruct, but it is not provably unreachable —
1157                // the comment below records that an inbound `UsePIX` does reach `handle_ssa_commit`
1158                // here. A knob that binds on some node roles and not others is the same defect
1159                // shape as a comment quoting a constant it does not reference.
1160                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                        // The same mapping as the Exit and Relay arms, deliberately: `DepositNeeded`
1166                        // is not *expected* here, but it is reachable. `SessionManager` has no
1167                        // notion of node role and this one runs with a live toolbox — only the
1168                        // incoming-session notification is drained below — so an inbound
1169                        // `StartSession` carrying `UsePIX` is accepted and ends in
1170                        // `handle_ssa_commit` emitting it. Panicking would take the whole PIX event
1171                        // task with it, stranding this node's own outbound deposits.
1172                        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                // Nodes without pix_events sink (no PIX configured at all)
1184                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        // ── Ssmgr startup ─────────────────────────────────────────────────
1195        // Entry nodes don't accept incoming sessions, relay/exit nodes do.
1196        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            // An Entry establishes Sessions rather than admitting them, so there is nothing to ask
1207            // about even if the caller installed a session server.
1208            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        // -- periodic counter flush
1225        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                // The grace sits inside the interval, so consecutive reports stay one interval apart.
1235                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        // -- periodic SURB round-trip flush
1254        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                    // Records the pending map could not hold are lost silently as far as every other
1277                    // counter is concerned; reporting what was lost since the last tick is what makes
1278                    // the loss visible.
1279                    #[cfg(all(feature = "telemetry", not(test)))]
1280                    METRIC_SURB_PENDING_LOST.increment_by(surb_round_trips.take_pending_lost());
1281                    // Drops the records outlived by their horizon, a part of the map per tick.
1282                    surb_round_trips.expire_step();
1283                    // Refresh the SURB-store gauge alongside the flush tick. The store updates its
1284                    // accounting synchronously, but nothing on the hot path samples it, so without a
1285                    // poller the series would be declared and never emitted. Once per flush interval
1286                    // is ample for a ceiling reading, and the walk is read-only.
1287                    #[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                    // Relayer health lives in the graph, so path selection prunes the dead and weights
1292                    // the stalled natively.
1293                    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                    // The counterparty sees only the first hop of the SURBs it holds, so it cannot tell
1303                    // which of them run through the dead relayer, and a FIFO store would spend them into
1304                    // the void until it turned over. Advancing the session's SURB generation makes it
1305                    // drop its whole stock on the next push. The write-off above is count-only (the SURBs
1306                    // through the relayer); the session's balancer is told the stock is gone instead, so
1307                    // that it refills from empty over the re-planned paths, at a pace (see
1308                    // `REFILL_PACING_SECS`) the paths can carry. The session is asked first: a session
1309                    // the manager no longer knows is only forgotten, its generation is not advanced
1310                    // (that would leave a stray entry in the store and log a bump for a closed session).
1311                    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                    // The counterparty still counts SURBs through a dead relayer, so each session is
1327                    // told how many of those it holds, to replace them. Walks the pending map, so it
1328                    // runs off the runtime worker like the write-off above, and only while some
1329                    // session has SURBs written off: with none there is nothing to count, and the
1330                    // empty figure clears the marks left from before. A full pool refuses the walk
1331                    // before it runs; the marks are then kept as they are until the next tick, since an
1332                    // empty figure would clear every session's mark only to set it again.
1333                    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, &current) {
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        // -- network probing
1362        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        // manual ping
1386        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        // Wire incoming: cover-traffic-filtered stream → probe classify → (session dispatch).
1397        // This stage must run in a background task, so the pipeline drains even when the
1398        // caller discards the returned HoprSocket (e.g. edge-node builder).
1399        //
1400        // The channel uses a resilient for_each rather than .forward() so that a disconnected
1401        // receiver (HoprSocket dropped without consuming) logs an error and continues rather
1402        // than collapsing the entire ingress pipeline. Callers should use HoprSocket::reader()
1403        // and actively drain the stream; see hopr-lib builder for the reference drain.
1404        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        // Populate the OnceLock at the end, making sure everything before didn't fail.
1427        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    /// Returns a reference to the network graph.
1521    pub fn graph(&self) -> &Graph {
1522        &self.graph
1523    }
1524
1525    /// Returns the per-relayer health, so connectivity events can report neighbours we lost or regained.
1526    pub fn relayer_health(&self) -> std::sync::Arc<protocol::surb_telemetry::RelayerHealth> {
1527        self.surb_round_trips.relayer_health()
1528    }
1529
1530    /// Returns a reference to the SURB store.
1531    ///
1532    /// Exposed so that chain-level channel events can invalidate stored SURBs whose return path
1533    /// starts with a relayer this node can no longer pay.
1534    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    /// Get connected peers with quality higher than some value.
1606    #[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                    // An unobserved edge has no score and cannot clear any threshold.
1620                    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
1633/// Maps a fully recovered SSA into the downstream event that carries the recovered deposit
1634/// key to the withdrawal strategy.
1635pub(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
1644/// How many PIX share resolutions may be dispatched into the [`SessionManager`] at once.
1645///
1646/// A dispatch can block: lifecycle events are delivered to a per-session supervisor over a bounded
1647/// channel, so a session whose supervisor is busy backpressures its sender. All sessions share this
1648/// one stream, so dispatching sequentially would let one such session hold up PIX progress — and
1649/// therefore the pipelined next-SSA request — for every other session on the node.
1650const PIX_EVENT_DISPATCH_CONCURRENCY: usize = 64;
1651
1652/// Maps a [`HoprSessionOutPixEvent`] into the upper-layer [`PixEvent`] carrying the deposit
1653/// instruction for the funding strategy.
1654fn 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            // What the Exit attached to this SSA in its `SsaRequest`, rebuilt by the Session layer
1666            // from the message. Empty when the Exit's pool produced none — `PixDepositData::is_empty`
1667            // is what tells the two apart, so there is nothing to signal here.
1668            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            // This node's own data coming back to it: the pool produced it for this SSA before the
1683            // request went out, and gets it returned now that the address it pays for is known.
1684            deposit_data,
1685            // Not optional as of hopr-api 4.0.1: the Exit always has a channel to report the deposit
1686            // on, and every `DepositAddressReceived` this maps from carries one.
1687            deposit_updated: notifier,
1688        }),
1689        // Straight through: `PixDepositDataRequest` is the pool's own request type, and the Session
1690        // layer neither adds to it nor reads the answers off the channel it carries.
1691        HoprSessionOutPixEvent::DepositDataRequest(request) => PixEvent::DepositDataRequest(request),
1692    }
1693}
1694
1695/// Notifies the [`SessionManager`] about a single PIX share resolution and returns the
1696/// upper-layer [`PixEvent`] it produces, if any.
1697async 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        // Feeds the supervisor's recovery deadlines and the egress gate's progress ceiling. A funded
1739        // Session that stops making progress stops being served, so dropping these outright would
1740        // stall a healthy Session rather than merely lose a statistic.
1741        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
1761/// Builds the Exit-side SSA reconstructor from operator configuration.
1762///
1763/// The single place `PixReconstructorConfig` becomes an `SsaReconstructorConfig`, called once per
1764/// node role that needs a reconstructor. Both production sites used to take
1765/// `SsaReconstructorConfig::default()` instead, which left all seven of the Exit's dials — capacity,
1766/// lifetimes, the acknowledgement window — unreachable from a config file.
1767///
1768/// `try_new` rather than `new`, for the same reason the generator uses it at the one call site
1769/// above: these values now come from an operator, so an out-of-range one is a startup error to
1770/// report and not a panic to take the node down with. `run_inner` has already validated
1771/// `self.cfg.pix` — `reconstructor` is `#[validate(nested)]` — so in practice this reports what that
1772/// validation would have caught anyway; it stays fallible because nothing in the type system says
1773/// the two must be called in that order.
1774fn 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
1780/// Turns the reconstructor's synchronous resolution wake-up into an asynchronous stream.
1781///
1782/// The one-slot channel carries only wake-ups, never resolutions. A full channel therefore means a
1783/// wake-up is already pending and can be safely coalesced; the resolutions themselves remain in the
1784/// reconstructor until this stream or the acknowledgement fallback atomically takes them.
1785fn 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/// Wires the Exit-side PIX machinery: [`PixToolbox`], the recovered-share channel and the
1811/// [`HoprTransportProcess::PixEvents`] task, returning the toolbox and the pipeline builder with
1812/// share processing attached.
1813///
1814/// Shared by the `(Exit, Some)` and `(Relay, Some)` arms of `run_inner`, which differ only in the
1815/// terminal `build_for_*` call and the relay's extra `with_ticket_events` step. Both need the exact
1816/// same wiring, and keeping it in one place is not cosmetic: the previous two copies had already
1817/// drifted, with the comment on the reconstructor config fixed in the Exit copy only.
1818///
1819/// The reconstructor arrives built, like the generator, so that [`ssa_reconstructor`] stays the one
1820/// place a config turns into one and this stays infallible.
1821///
1822/// The caller keeps the terminal, so this returns the builder rather than the built processes.
1823/// Only the `exit_ack_proc` and `ssa_events` type parameters change; the rest pass through
1824/// untouched, which is why none of them carry bounds here.
1825#[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
1875/// Builds the merged PIX event stream feeding the upper layer.
1876///
1877/// Combines the Session-originated deposit instructions with the share resolutions coming out of
1878/// the packet pipeline. Share resolutions are dispatched into the `SessionManager` concurrently
1879/// (see [`PIX_EVENT_DISPATCH_CONCURRENCY`]).
1880///
1881/// Concurrency does not require ordering guarantees here: events for one session converge on that
1882/// session's supervisor, which is a single-threaded state machine whose handlers are idempotent per
1883/// phase and whose counters are absolute rather than incremental. Of the events belonging to one
1884/// cycle exactly one advances it and the rest are recognised as stale, whatever order they arrive
1885/// in.
1886fn 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
1901// ---------------------------------------------------------------------------
1902// NetworkView impl for HoprTransport — wraps OnceLock<Net> access
1903// ---------------------------------------------------------------------------
1904
1905impl<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// ---------------------------------------------------------------------------
1944// TransportOperations impl for HoprTransport
1945// ---------------------------------------------------------------------------
1946
1947#[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
1985/// Maximum application-layer payload that fits in a single HOPR sphinx packet (bytes).
1986pub 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    /// A commitment that redeems the final deferred acknowledgement must deliver the recovered key
2013    /// without waiting for another acknowledgement batch that may never arrive.
2014    #[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        // Every share and acknowledgement arrives before the client commitment, so all of them
2041        // defer waiting for their verifier and this acknowledgement call returns no resolution.
2042        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        // This is the final input. In particular, there is no acknowledge_shares call below to
2063        // pull a parked resolution out of the reconstructor.
2064        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        // The wake-up is coalesced and the buffer is atomically taken, so the same recovery cannot
2081        // be emitted a second time.
2082        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        //! Capture structured records and formatted ancestry using the same subscriber.
2103        //!
2104        //! Tests asserting routing event counts use `serial_test::serial(routing_logs)` to isolate
2105        //! subscriber registration and its process-wide callsite cache from other capture tests.
2106
2107        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                // Keep the scoped dispatcher installed through utility task/span destruction, not just
2153                // the decoder callback. Production workers use the process-wide subscriber.
2154                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                    // Scoped test subscribers run concurrently with different filters. Check the active
2188                    // subscriber on each event rather than caching a callsite's interest at a fixed level.
2189                    .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    /// The admission seam's `raise_target` must reach the store, and only for the admission it names.
2273    ///
2274    /// `StoreSurbAdmission` is pure delegation, so this pins the wiring the SessionManager relies on:
2275    /// a raised target widens the ring the token names, and a stale token (a successor Session's
2276    /// admission) leaves the resident ring at the size its own admission gave it.
2277    #[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        // The ping tier, then the main tier the client ramps to.
2291        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        // A successor's admission invalidates the predecessor's token; the raise must then be a no-op.
2305        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        // And retiring through the seam still releases the admission the store minted.
2316        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    /// A Session that announces the largest target the transport allows is admitted a full-size ring.
2326    ///
2327    /// The Exit gives a Session that announced no target exactly that figure
2328    /// (`maximum_surb_buffer_size`, set from `surb_buffer_target_ceiling`), so this is the link that
2329    /// makes such a Session's ring `rb_capacity` and not the few dozen SURBs the balancer's fallback
2330    /// would give it: the ceiling is two thirds of the capacity, and the store's default headroom of
2331    /// 50 % takes it back up. Integer division can leave it a SURB short.
2332    ///
2333    /// It pins the store arithmetic only. It calls `surb_buffer_target_ceiling` itself, so it would not
2334    /// notice the transport ceasing to set `maximum_surb_buffer_size` from it: the session manager
2335    /// config is built inline in `HoprTransport::new`, which has no seam small enough to test here.
2336    #[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}