1use std::fmt::Debug;
32
33use nautilus_core::string::secret::REDACTED;
34use tokio_tungstenite::tungstenite::stream::Mode;
35
36use super::types::TcpMessageHandler;
37use crate::error::{NetworkConfigError, NetworkConfigResult};
38
39#[derive(Clone, Debug, PartialEq, Eq)]
44pub struct SocketHeartbeat {
45 pub interval_secs: u64,
49 pub payload: Vec<u8>,
51}
52
53#[derive(Clone, bon::Builder)]
55#[builder(finish_fn(name = build_inner, vis = ""))]
56pub struct SocketConfig {
57 pub url: String,
59 pub mode: Mode,
61 pub suffix: Vec<u8>,
63 pub message_handler: Option<TcpMessageHandler>,
65 pub heartbeat: Option<SocketHeartbeat>,
77 pub connect_timeout_ms: Option<u64>,
83 pub reconnect_delay_initial_ms: Option<u64>,
85 pub reconnect_delay_max_ms: Option<u64>,
87 pub reconnect_backoff_factor: Option<f64>,
89 pub reconnect_jitter_ms: Option<u64>,
91 pub connection_max_retries: Option<u32>,
96 pub reconnect_max_attempts: Option<u32>,
103 pub heartbeat_timeout_secs: Option<u64>,
118 pub writer_capacity: Option<usize>,
123 pub certs_dir: Option<String>,
133}
134
135impl<S: socket_config_builder::IsComplete> SocketConfigBuilder<S> {
136 pub fn build(self) -> NetworkConfigResult<SocketConfig> {
142 let config = self.build_inner();
143 config.validate()?;
144 Ok(config)
145 }
146}
147
148impl SocketConfig {
149 pub fn validate(&self) -> NetworkConfigResult<()> {
158 let mut errors = Vec::new();
159 if let Err(e) = crate::writer::validate_capacity(self.writer_capacity) {
160 errors.push(e);
161 }
162
163 if self.url.trim().is_empty() {
164 errors.push(NetworkConfigError::invalid("url", "must not be empty"));
165 }
166
167 if let Some(heartbeat) = &self.heartbeat
168 && heartbeat.interval_secs == 0
169 {
170 errors.push(NetworkConfigError::invalid(
171 "heartbeat",
172 "interval must be positive",
173 ));
174 }
175
176 if let (Some(heartbeat), Some(timeout_secs)) =
179 (&self.heartbeat, self.heartbeat_timeout_secs)
180 && timeout_secs <= heartbeat.interval_secs
181 {
182 errors.push(NetworkConfigError::invalid(
183 "heartbeat_timeout_secs",
184 format!(
185 "must exceed heartbeat interval ({}s), was {timeout_secs}s",
186 heartbeat.interval_secs
187 ),
188 ));
189 }
190
191 for (field, value) in [
194 ("connect_timeout_ms", self.connect_timeout_ms),
195 (
196 "reconnect_delay_initial_ms",
197 self.reconnect_delay_initial_ms,
198 ),
199 ("reconnect_delay_max_ms", self.reconnect_delay_max_ms),
200 ("heartbeat_timeout_secs", self.heartbeat_timeout_secs),
201 ] {
202 if let Some(value) = value
203 && value == 0
204 {
205 errors.push(NetworkConfigError::invalid(
206 field,
207 format!("must be positive, was {value}"),
208 ));
209 }
210 }
211
212 if let Some(factor) = self.reconnect_backoff_factor
213 && !(1.0..=100.0).contains(&factor)
214 {
215 errors.push(NetworkConfigError::invalid(
216 "reconnect_backoff_factor",
217 format!("must be in range [1.0, 100.0], was {factor}"),
218 ));
219 }
220
221 if let (Some(initial), Some(max)) =
222 (self.reconnect_delay_initial_ms, self.reconnect_delay_max_ms)
223 && initial > max
224 {
225 errors.push(NetworkConfigError::invalid(
226 "reconnect_delay_initial_ms",
227 format!("must not exceed reconnect_delay_max_ms ({max}), was {initial}"),
228 ));
229 }
230
231 NetworkConfigError::collect(errors)
232 }
233
234 pub(crate) fn resolved_heartbeat_timeout(&self) -> Option<u64> {
235 crate::heartbeat::resolve_heartbeat_timeout(
236 self.heartbeat_timeout_secs,
237 self.heartbeat
238 .as_ref()
239 .map(|heartbeat| heartbeat.interval_secs),
240 )
241 }
242}
243
244impl Debug for SocketConfig {
245 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
246 f.debug_struct(stringify!(SocketConfig))
247 .field("url", &REDACTED)
248 .field("mode", &self.mode)
249 .field("suffix", &self.suffix)
250 .field(
251 "message_handler",
252 &self.message_handler.as_ref().map(|_| "<function>"),
253 )
254 .field("heartbeat", &self.heartbeat)
255 .field("writer_capacity", &self.writer_capacity)
256 .field("connect_timeout_ms", &self.connect_timeout_ms)
257 .field(
258 "reconnect_delay_initial_ms",
259 &self.reconnect_delay_initial_ms,
260 )
261 .field("reconnect_delay_max_ms", &self.reconnect_delay_max_ms)
262 .field("reconnect_backoff_factor", &self.reconnect_backoff_factor)
263 .field("reconnect_jitter_ms", &self.reconnect_jitter_ms)
264 .field("connection_max_retries", &self.connection_max_retries)
265 .field("reconnect_max_attempts", &self.reconnect_max_attempts)
266 .field("heartbeat_timeout_secs", &self.heartbeat_timeout_secs)
267 .field("certs_dir", &self.certs_dir)
268 .finish()
269 }
270}
271
272#[cfg(test)]
273mod tests {
274 use rstest::rstest;
275 use tokio_tungstenite::tungstenite::stream::Mode;
276
277 use super::{SocketConfig, SocketHeartbeat};
278 use crate::error::NetworkConfigError;
279
280 fn valid_config() -> SocketConfig {
281 SocketConfig::builder()
282 .url("tcp://127.0.0.1:8080".to_string())
283 .mode(Mode::Plain)
284 .suffix(vec![b'\n'])
285 .build()
286 .expect("baseline socket config should be valid")
287 }
288
289 #[rstest]
290 fn test_builder_accepts_valid_config() {
291 let result = SocketConfig::builder()
292 .url("tcp://127.0.0.1:8080".to_string())
293 .mode(Mode::Plain)
294 .suffix(vec![b'\n'])
295 .build();
296
297 assert!(result.is_ok());
298 }
299
300 #[rstest]
301 fn test_validate_accepts_zero_jitter() {
302 let mut config = valid_config();
303 config.reconnect_jitter_ms = Some(0);
304
305 assert!(config.validate().is_ok());
306 }
307
308 #[rstest]
309 fn test_validate_accepts_heartbeat_with_payload() {
310 let mut config = valid_config();
311 config.heartbeat = Some(SocketHeartbeat {
312 interval_secs: 5,
313 payload: b"ping".to_vec(),
314 });
315
316 assert!(config.validate().is_ok());
317 }
318
319 #[rstest]
320 #[case::derived(None, Some(15))]
321 #[case::explicit_wins(Some(20), Some(20))]
322 fn test_resolve_timeout_from_socket_heartbeat(
323 #[case] timeout_secs: Option<u64>,
324 #[case] expected: Option<u64>,
325 ) {
326 let mut config = valid_config();
327 config.heartbeat = Some(SocketHeartbeat {
328 interval_secs: 5,
329 payload: b"ping".to_vec(),
330 });
331
332 config.heartbeat_timeout_secs = timeout_secs;
333
334 assert_eq!(config.resolved_heartbeat_timeout(), expected);
335 }
336
337 #[rstest]
338 #[case::writer_capacity_zero(|c: &mut SocketConfig| c.writer_capacity = Some(0), "writer_capacity")]
339 #[case::writer_capacity_excess(|c: &mut SocketConfig| c.writer_capacity = Some(usize::MAX), "writer_capacity")]
340 #[case::empty_url(|c: &mut SocketConfig| c.url = String::new(), "url")]
341 #[case::heartbeat_interval(|c: &mut SocketConfig| { c.heartbeat = Some(SocketHeartbeat { interval_secs: 0, payload: vec![] }); }, "heartbeat")]
342 #[case::heartbeat_timeout_below_interval(|c: &mut SocketConfig| { c.heartbeat = Some(SocketHeartbeat { interval_secs: 5, payload: vec![b'p'] }); c.heartbeat_timeout_secs = Some(5); }, "heartbeat_timeout_secs")]
343 #[case::connect_timeout(|c: &mut SocketConfig| c.connect_timeout_ms = Some(0), "connect_timeout_ms")]
344 #[case::reconnect_delay_initial(|c: &mut SocketConfig| c.reconnect_delay_initial_ms = Some(0), "reconnect_delay_initial_ms")]
345 #[case::reconnect_delay_max(|c: &mut SocketConfig| c.reconnect_delay_max_ms = Some(0), "reconnect_delay_max_ms")]
346 #[case::heartbeat_timeout_zero(|c: &mut SocketConfig| c.heartbeat_timeout_secs = Some(0), "heartbeat_timeout_secs")]
347 fn test_validate_rejects_invalid_field(
348 #[case] mutate: fn(&mut SocketConfig),
349 #[case] expected_field: &str,
350 ) {
351 let mut config = valid_config();
352 mutate(&mut config);
353
354 let err = config
355 .validate()
356 .expect_err("invalid value should be rejected");
357
358 assert!(
359 matches!(err, NetworkConfigError::Invalid { field, .. } if field == expected_field)
360 );
361 }
362
363 #[rstest]
364 #[case::too_small(0.5)]
365 #[case::too_large(100.1)]
366 #[case::nan(f64::NAN)]
367 #[case::infinite(f64::INFINITY)]
368 fn test_validate_rejects_invalid_backoff_factor(#[case] factor: f64) {
369 let mut config = valid_config();
370 config.reconnect_backoff_factor = Some(factor);
371
372 let err = config
373 .validate()
374 .expect_err("invalid backoff factor should be rejected");
375
376 assert!(
377 matches!(err, NetworkConfigError::Invalid { field, .. } if field == "reconnect_backoff_factor")
378 );
379 }
380
381 #[rstest]
382 fn test_validate_rejects_delay_initial_exceeding_max() {
383 let mut config = valid_config();
384 config.reconnect_delay_initial_ms = Some(5_000);
385 config.reconnect_delay_max_ms = Some(1_000);
386
387 let err = config
388 .validate()
389 .expect_err("initial delay above max should be rejected");
390
391 assert!(
392 matches!(err, NetworkConfigError::Invalid { field, .. } if field == "reconnect_delay_initial_ms")
393 );
394 }
395
396 #[rstest]
397 fn test_validate_collects_multiple_errors() {
398 let mut config = valid_config();
399 config.url = String::new();
400 config.connect_timeout_ms = Some(0);
401
402 let err = config.validate().expect_err("multiple invalid fields");
403
404 match err {
405 NetworkConfigError::Multiple { errors } => assert_eq!(errors.len(), 2),
406 other @ NetworkConfigError::Invalid { .. } => {
407 panic!("expected Multiple, was {other:?}")
408 }
409 }
410 }
411
412 #[rstest]
413 fn test_debug_redacts_endpoint_credentials() {
414 const ENDPOINT_PATH_SECRET: &str = "unique-endpoint-path-secret";
415 const ENDPOINT_QUERY_SECRET: &str = "unique-endpoint-query-secret";
416 let mut config = valid_config();
417 config.url =
418 format!("wss://rpc.example.com/{ENDPOINT_PATH_SECRET}?api_key={ENDPOINT_QUERY_SECRET}");
419
420 let debug = format!("{config:?}");
421
422 assert!(debug.contains("url: \"<redacted>\""));
423 assert!(!debug.contains(ENDPOINT_PATH_SECRET));
424 assert!(!debug.contains(ENDPOINT_QUERY_SECRET));
425 }
426}