//! Engine configuration. use std::path::PathBuf; use std::time::Duration; use crate::error::{NetworkError, Result}; use crate::protocol::{ALPN, NetworkId, SchemaId}; use crate::rendezvous::RendezvousConfig; /// Default maximum size of an encoded domain message (256 KiB). pub const DEFAULT_MAX_MESSAGE_SIZE: usize = 256 * 1024; /// Default timeout applied to handshakes and message round-trips. pub const DEFAULT_REQUEST_TIMEOUT: Duration = Duration::from_secs(10); /// Default capacity of the event channel. pub const DEFAULT_EVENT_CHANNEL_CAPACITY: usize = 1024; /// Default limit of concurrently processed streams per peer. pub const DEFAULT_MAX_CONCURRENT_STREAMS_PER_PEER: usize = 64; /// Configuration for a [`crate::NetworkEngine`]. /// /// Use [`NetworkConfig::builder`] to construct a validated instance. #[derive(Debug, Clone)] pub struct NetworkConfig { /// Directory where the persistent peer identity is stored. pub data_dir: PathBuf, /// Identifier of the network this peer participates in. pub network_id: NetworkId, /// Identifier of the domain message schema. pub schema_id: SchemaId, /// Maximum size in bytes of a single encoded domain message. pub max_message_size: usize, /// Timeout applied to handshakes and message round-trips. pub request_timeout: Duration, /// Capacity of the bounded event channel. pub event_channel_capacity: usize, /// Maximum number of concurrently processed streams per peer. pub max_concurrent_streams_per_peer: usize, /// Automatic peer discovery over the mainline DHT; `None` disables it and /// peers are connected via tickets only. pub rendezvous: Option, /// Auxiliary ALPN protocols on which this peer accepts raw byte streams /// (see [`crate::NetworkEngine::stream_acceptor`]). pub stream_protocols: Vec>, /// Auxiliary stream protocols whose handshake is independent of the /// application schema. Intended for compatibility/capability discovery. pub schema_independent_stream_protocols: Vec>, } impl NetworkConfig { /// Returns a new [`NetworkConfigBuilder`]. pub fn builder() -> NetworkConfigBuilder { NetworkConfigBuilder::default() } } /// Builder for [`NetworkConfig`]. /// /// `data_dir`, `network_id` and `schema_id` are required; everything else has /// sensible defaults. #[derive(Debug, Default, Clone)] pub struct NetworkConfigBuilder { data_dir: Option, network_id: Option, schema_id: Option, max_message_size: Option, request_timeout: Option, event_channel_capacity: Option, max_concurrent_streams_per_peer: Option, rendezvous: Option, stream_protocols: Vec>, schema_independent_stream_protocols: Vec>, } impl NetworkConfigBuilder { /// Sets the directory where the persistent peer identity is stored. pub fn data_dir(mut self, dir: impl Into) -> Self { self.data_dir = Some(dir.into()); self } /// Sets the network identifier. pub fn network_id(mut self, network_id: NetworkId) -> Self { self.network_id = Some(network_id); self } /// Sets the schema identifier. pub fn schema_id(mut self, schema_id: SchemaId) -> Self { self.schema_id = Some(schema_id); self } /// Sets the maximum size in bytes of a single encoded domain message. pub fn max_message_size(mut self, size: usize) -> Self { self.max_message_size = Some(size); self } /// Sets the timeout applied to handshakes and message round-trips. pub fn request_timeout(mut self, timeout: Duration) -> Self { self.request_timeout = Some(timeout); self } /// Sets the capacity of the bounded event channel. pub fn event_channel_capacity(mut self, capacity: usize) -> Self { self.event_channel_capacity = Some(capacity); self } /// Sets the maximum number of concurrently processed streams per peer. pub fn max_concurrent_streams_per_peer(mut self, limit: usize) -> Self { self.max_concurrent_streams_per_peer = Some(limit); self } /// Enables automatic peer discovery over the mainline DHT. pub fn rendezvous(mut self, rendezvous: RendezvousConfig) -> Self { self.rendezvous = Some(rendezvous); self } /// Declares an auxiliary ALPN protocol on which this peer accepts raw /// byte streams (see [`crate::NetworkEngine::stream_acceptor`]). May be /// called multiple times, once per protocol. pub fn stream_protocol(mut self, alpn: impl Into>) -> Self { self.stream_protocols.push(alpn.into()); self } /// Declares an auxiliary ALPN protocol that validates the network and /// federation transport version, but deliberately does not require the /// application schema id to match. /// /// This is suitable for bounded, self-versioned capability discovery /// protocols that must remain reachable across schema upgrades. pub fn schema_independent_stream_protocol(mut self, alpn: impl Into>) -> Self { self.schema_independent_stream_protocols.push(alpn.into()); self } /// Validates the configuration and builds a [`NetworkConfig`]. pub fn build(self) -> Result { let data_dir = self .data_dir .ok_or_else(|| NetworkError::InvalidConfig("data_dir is required".into()))?; let network_id = self .network_id .ok_or_else(|| NetworkError::InvalidConfig("network_id is required".into()))?; let schema_id = self .schema_id .ok_or_else(|| NetworkError::InvalidConfig("schema_id is required".into()))?; if data_dir.as_os_str().is_empty() { return Err(NetworkError::InvalidConfig( "data_dir must not be empty".into(), )); } let max_message_size = self.max_message_size.unwrap_or(DEFAULT_MAX_MESSAGE_SIZE); if max_message_size == 0 { return Err(NetworkError::InvalidConfig( "max_message_size must be greater than zero".into(), )); } if max_message_size > u32::MAX as usize { return Err(NetworkError::InvalidConfig( "max_message_size must fit into a 32-bit length prefix".into(), )); } let request_timeout = self.request_timeout.unwrap_or(DEFAULT_REQUEST_TIMEOUT); if request_timeout.is_zero() { return Err(NetworkError::InvalidConfig( "request_timeout must be greater than zero".into(), )); } let event_channel_capacity = self .event_channel_capacity .unwrap_or(DEFAULT_EVENT_CHANNEL_CAPACITY); if event_channel_capacity == 0 { return Err(NetworkError::InvalidConfig( "event_channel_capacity must be greater than zero".into(), )); } let max_concurrent_streams_per_peer = self .max_concurrent_streams_per_peer .unwrap_or(DEFAULT_MAX_CONCURRENT_STREAMS_PER_PEER); if max_concurrent_streams_per_peer == 0 { return Err(NetworkError::InvalidConfig( "max_concurrent_streams_per_peer must be greater than zero".into(), )); } if let Some(rendezvous) = &self.rendezvous { if rendezvous.interval.is_zero() { return Err(NetworkError::InvalidConfig( "rendezvous interval must be greater than zero".into(), )); } if rendezvous.entry_ttl.is_zero() { return Err(NetworkError::InvalidConfig( "rendezvous entry_ttl must be greater than zero".into(), )); } } for (index, alpn) in self.stream_protocols.iter().enumerate() { if alpn.is_empty() { return Err(NetworkError::InvalidConfig( "stream protocol ALPN must not be empty".into(), )); } if alpn.as_slice() == ALPN { return Err(NetworkError::InvalidConfig( "stream protocol ALPN must differ from the engine ALPN".into(), )); } if self.stream_protocols[..index].contains(alpn) { return Err(NetworkError::InvalidConfig(format!( "duplicate stream protocol ALPN: {}", String::from_utf8_lossy(alpn) ))); } } for (index, alpn) in self.schema_independent_stream_protocols.iter().enumerate() { if alpn.is_empty() { return Err(NetworkError::InvalidConfig( "schema-independent stream protocol ALPN must not be empty".into(), )); } if alpn.as_slice() == ALPN { return Err(NetworkError::InvalidConfig( "schema-independent stream protocol ALPN must differ from the engine ALPN" .into(), )); } if self.schema_independent_stream_protocols[..index].contains(alpn) || self.stream_protocols.contains(alpn) { return Err(NetworkError::InvalidConfig(format!( "duplicate stream protocol ALPN: {}", String::from_utf8_lossy(alpn) ))); } } Ok(NetworkConfig { data_dir, network_id, schema_id, max_message_size, request_timeout, event_channel_capacity, max_concurrent_streams_per_peer, rendezvous: self.rendezvous, stream_protocols: self.stream_protocols, schema_independent_stream_protocols: self.schema_independent_stream_protocols, }) } } #[cfg(test)] mod tests { use super::*; fn base_builder() -> NetworkConfigBuilder { NetworkConfig::builder() .data_dir("./some-dir") .network_id(NetworkId::from_name("test-network")) .schema_id(SchemaId::from_name("test-schema")) } #[test] fn builder_applies_defaults() { let config = base_builder().build().expect("valid config"); assert_eq!(config.max_message_size, DEFAULT_MAX_MESSAGE_SIZE); assert_eq!(config.request_timeout, DEFAULT_REQUEST_TIMEOUT); assert_eq!( config.event_channel_capacity, DEFAULT_EVENT_CHANNEL_CAPACITY ); assert_eq!( config.max_concurrent_streams_per_peer, DEFAULT_MAX_CONCURRENT_STREAMS_PER_PEER ); } #[test] fn builder_rejects_missing_required_fields() { assert!(NetworkConfig::builder().build().is_err()); assert!( NetworkConfig::builder() .data_dir("./dir") .network_id(NetworkId::from_name("n")) .build() .is_err() ); } #[test] fn builder_rejects_invalid_values() { assert!(base_builder().max_message_size(0).build().is_err()); assert!( base_builder() .request_timeout(Duration::ZERO) .build() .is_err() ); assert!(base_builder().event_channel_capacity(0).build().is_err()); assert!( base_builder() .max_concurrent_streams_per_peer(0) .build() .is_err() ); } #[test] fn rendezvous_is_disabled_by_default_and_validated_when_set() { let config = base_builder().build().expect("valid config"); assert!(config.rendezvous.is_none()); let config = base_builder() .rendezvous(RendezvousConfig::default()) .build() .expect("valid config"); assert!(config.rendezvous.is_some()); let zero_interval = RendezvousConfig { interval: Duration::ZERO, ..RendezvousConfig::default() }; assert!(base_builder().rendezvous(zero_interval).build().is_err()); let zero_ttl = RendezvousConfig { entry_ttl: Duration::ZERO, ..RendezvousConfig::default() }; assert!(base_builder().rendezvous(zero_ttl).build().is_err()); } #[test] fn stream_protocols_are_validated() { let config = base_builder().build().expect("valid config"); assert!(config.stream_protocols.is_empty()); let config = base_builder() .stream_protocol("my-app/blob/1") .stream_protocol("my-app/other/1") .build() .expect("valid config"); assert_eq!(config.stream_protocols.len(), 2); assert!(base_builder().stream_protocol("").build().is_err()); assert!(base_builder().stream_protocol(ALPN).build().is_err()); assert!( base_builder() .stream_protocol("dup/1") .stream_protocol("dup/1") .build() .is_err() ); assert!( base_builder() .stream_protocol("dup/1") .schema_independent_stream_protocol("dup/1") .build() .is_err() ); let config = base_builder() .schema_independent_stream_protocol("furumi/capabilities/1") .build() .expect("valid schema-independent stream protocol"); assert_eq!( config.schema_independent_stream_protocols, vec![b"furumi/capabilities/1".to_vec()] ); } }