hopr_transport_session/
lib.rs

1//! [`Session`] object providing the session functionality over the HOPR transport
2//!
3//! The session proxies the user interactions with the transport to hide the
4//! advanced interactions and functionality.
5//!
6//! The [`SessionManager`] allows for automatic management of sessions via the Start protocol.
7//!
8//! This crate implements [RFC-0007](https://github.com/hoprnet/rfc/tree/main/rfcs/RFC-0007-session-protocol).
9pub(crate) mod balancer;
10pub mod errors;
11mod initiation;
12mod manager;
13pub mod traits;
14mod types;
15
16use std::collections::HashSet;
17
18pub use balancer::SurbBalancerConfig;
19use hopr_internal_types::prelude::HoprPseudonym;
20use hopr_network_types::prelude::state::{SessionFeature, SessionSocket};
21pub use hopr_network_types::types::*;
22use hopr_transport_packet::prelude::ApplicationData;
23pub use manager::{DispatchResult, MIN_BALANCER_SAMPLING_INTERVAL, SessionManager, SessionManagerConfig};
24#[cfg(feature = "runtime-tokio")]
25pub use types::transfer_session;
26pub use types::{IncomingSession, ServiceId, Session, SessionId, SessionTarget};
27
28// TODO: resolve this in #7145
29#[cfg(not(feature = "serde"))]
30compile_error!("The `serde` feature currently must be enabled, see #7145");
31
32/// Number of bytes that can be sent in a single Session protocol payload.
33pub const SESSION_PAYLOAD_SIZE: usize = SessionSocket::<{ ApplicationData::PAYLOAD_SIZE }>::PAYLOAD_CAPACITY;
34
35flagset::flags! {
36    /// Individual capabilities of a Session.
37    #[repr(u8)]
38    #[derive(strum::EnumString, strum::Display)]
39    #[cfg_attr(feature = "serde", derive(serde_repr::Serialize_repr, serde_repr::Deserialize_repr))]
40    pub enum Capability : u8 {
41        /// No capabilities.
42        None = 0,
43        /// Frame segmentation.
44        Segmentation = 0b1000,
45        /// Frame retransmission (ACK-based)
46        ///
47        /// Implies [`Segmentation`].
48        RetransmissionAck = 0b1100,
49        /// Frame retransmission (NACK-based)
50        ///
51        /// Implies [`Segmentation`].
52        RetransmissionNack = 0b1010,
53        /// Disable packet buffering
54        ///
55        /// Implies [`Segmentation`].
56        NoDelay = 0b1001,
57    }
58}
59
60/// Set of Session [capabilities](Capability).
61pub type Capabilities = flagset::FlagSet<Capability>;
62
63// Converts a set of capabilities to a set of Session features.
64// TODO: remove this in 3.1
65pub(crate) fn capabilities_to_features(value: &Capabilities) -> HashSet<SessionFeature> {
66    let mut ret = HashSet::new();
67    if value.contains(Capability::NoDelay) {
68        ret.insert(SessionFeature::NoDelay);
69    }
70
71    if value.contains(Capability::RetransmissionAck) {
72        ret.extend(&[SessionFeature::AcknowledgeFrames, SessionFeature::RetransmitFrames]);
73    }
74
75    if value.contains(Capability::RetransmissionNack) {
76        ret.extend(&[
77            SessionFeature::AcknowledgeFrames,
78            SessionFeature::RequestIncompleteFrames,
79        ]);
80    }
81
82    ret
83}
84
85/// Configuration for the session.
86///
87/// Relevant primarily for the client, since the server is only
88/// a reactive component in regard to the session concept.
89#[derive(Debug, PartialEq, Clone, smart_default::SmartDefault)]
90pub struct SessionClientConfig {
91    /// The forward path options for the session.
92    #[default(RoutingOptions::Hops(hopr_primitive_types::bounded::BoundedSize::MIN))]
93    pub forward_path_options: RoutingOptions,
94    /// The return path options for the session.
95    #[default(RoutingOptions::Hops(hopr_primitive_types::bounded::BoundedSize::MIN))]
96    pub return_path_options: RoutingOptions,
97    /// Capabilities offered by the session.
98    #[default(_code = "Capability::Segmentation.into()")]
99    pub capabilities: Capabilities,
100    /// Optional pseudonym used for the session. Mostly useful for testing only.
101    #[default(None)]
102    pub pseudonym: Option<HoprPseudonym>,
103    /// Enable automatic SURB management for the Session.
104    #[default(Some(SurbBalancerConfig::default()))]
105    pub surb_management: Option<SurbBalancerConfig>,
106}
hopr_transport_session/lib.rs

hopr_transport_session/
lib.rs
