open-net 0.3.5

A cross-platform async networking library for Rust with HTTP and WebSocket clients, network status monitoring, configurable retries, WebSocket reconnection and heartbeats, and managed client lifecycles. Reuse common networking infrastructure across applications to avoid repeated implementation and debugging, helping save development time and AI coding tokens.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
use crate::error::NetError;
use crate::Result;
use std::time::{Duration, Instant};
use tokio::sync::Semaphore;

// These executors create a fixed set of workers. The data executor instead
// grows lazily and is bounded by its existing semaphore budget.
const MAX_FIXED_CALLBACK_WORKERS: usize = 256;
const MAX_HEARTBEAT_PONG_RECOVERY_ATTEMPTS: usize = 10;
const MAX_HEARTBEAT_PING_WRITE_RETRIES: usize = 1024;

/// Shared resource limits, transport parameters, and heartbeat configuration for WebSocket clients.
#[derive(Clone, Debug)]
pub struct WebSocketClientConfig {
    /// Default replay policy for untracked message writes. Initially disabled.
    pub default_send_retry_policy: super::WsSendRetryPolicy,
    /// Default policy for factory-backed logical requests. Initially disabled.
    pub default_request_retry_policy: super::WsRequestRetryPolicy,
    /// Capacity of command, I/O event, and normal and emergency send queues.
    pub queues: QueueLimits,
    /// Resource caps for receiving messages, subscribing to distribution, callback execution, and blocking handshake tasks.
    pub dispatch: DispatchLimits,
    /// Number of pending requests and manual response handling grace configuration.
    pub requests: RequestLimits,
    /// WebSocket frame fragmentation, read and write buffers and sizes, timeout limits.
    pub frames: FrameConfig,
    /// Low-level TCP socket options.
    pub tcp: TcpConfig,
    /// Active Ping/Pong heartbeat configuration; `None` means disabling active heartbeat.
    pub heartbeat: Option<HeartbeatConfig>,
    /// Maximum time to wait for the closing handshake and I/O task to finish
    /// during shutdown; the default is 2 seconds.
    pub close_timeout: Duration,
}

impl Default for WebSocketClientConfig {
    fn default() -> Self {
        Self {
            default_send_retry_policy: super::WsSendRetryPolicy::no_retry(),
            default_request_retry_policy: super::WsRequestRetryPolicy::no_retry(),
            queues: QueueLimits::default(),
            dispatch: DispatchLimits::default(),
            requests: RequestLimits::default(),
            frames: FrameConfig::default(),
            tcp: TcpConfig::default(),
            heartbeat: Some(HeartbeatConfig::default()),
            close_timeout: Duration::from_secs(2),
        }
    }
}

impl WebSocketClientConfig {
    pub fn with_default_send_retry_policy(mut self, policy: super::WsSendRetryPolicy) -> Self {
        self.default_send_retry_policy = policy;
        self
    }
    pub fn with_default_request_retry_policy(
        mut self,
        policy: super::WsRequestRetryPolicy,
    ) -> Self {
        self.default_request_retry_policy = policy;
        self
    }
    /// Validates all nested limits and transport settings before client creation.
    pub fn validate(&self) -> Result<()> {
        self.queues.validate()?;
        self.dispatch.validate()?;
        self.requests.validate()?;
        self.frames.validate()?;
        self.tcp.validate()?;
        if let Some(heartbeat) = &self.heartbeat {
            heartbeat.validate()?;
        }
        deadline(self.close_timeout, "close_timeout", false)?;
        if self.frames.data_frame_payload_size.is_none() {
            let payload = self
                .queues
                .normal
                .max_bytes
                .max(self.queues.urgent.max_bytes);
            self.frames.validate_outgoing_payload(payload)?;
        }
        Ok(())
    }
}

/// Double caps on the number of entries and bytes in a queue or resource pool.
#[derive(Clone, Debug)]
pub struct QueueLimit {
    /// The maximum number of entries that can be occupied simultaneously must be greater than zero.
    pub max_items: usize,
    /// The upper limit of the total number of payload bytes that can be occupied simultaneously must be greater than zero.
    pub max_bytes: usize,
}

impl Default for QueueLimit {
    fn default() -> Self {
        Self {
            max_items: 128,
            max_bytes: 1024 * 1024,
        }
    }
}

impl QueueLimit {
    /// Validates that both entry and byte limits are representable and non-zero.
    pub fn validate(&self) -> Result<()> {
        self.validate_fields("max_items", "max_bytes")
    }

    pub(super) fn validate_fields(&self, items_field: &str, bytes_field: &str) -> Result<()> {
        permits(self.max_items, items_field)?;
        permits(self.max_bytes, bytes_field)?;
        if self.max_bytes > u32::MAX as usize {
            return Err(NetError::config(
                bytes_field,
                "must fit a u32 byte allowance",
            ));
        }
        Ok(())
    }
}

/// Queue capacity for client internal commands, I/O events, and two send channels.
#[derive(Clone, Debug)]
pub struct QueueLimits {
    /// The maximum number of commands that the client command queue can accommodate, default 128.
    pub commands: usize,
    /// The maximum number of events that the I/O event queue can accommodate, default 128.
    pub io_events: usize,
    /// The upper limit of entries and payload bytes for ordinary send channels, default is 1024 entries, 16 MiB.
    pub normal: QueueLimit,
    /// Independent capacity of emergency sending channels, default 64, 1 MiB.
    pub urgent: QueueLimit,
}

impl Default for QueueLimits {
    fn default() -> Self {
        Self {
            commands: 128,
            io_events: 128,
            normal: QueueLimit {
                max_items: 1024,
                max_bytes: 16 * 1024 * 1024,
            },
            urgent: QueueLimit {
                max_items: 64,
                max_bytes: 1024 * 1024,
            },
        }
    }
}

impl QueueLimits {
    /// Validates command, event, and send-queue capacities.
    pub fn validate(&self) -> Result<()> {
        permits(self.commands, "queues.commands")?;
        permits(self.io_events, "queues.io_events")?;
        self.normal
            .validate_fields("queues.normal.max_items", "queues.normal.max_bytes")?;
        self.urgent
            .validate_fields("queues.urgent.max_items", "queues.urgent.max_bytes")
    }
}

/// Upper limit on client-shared message distribution, subscription, and callback execution resources.
#[derive(Clone, Debug)]
pub struct DispatchLimits {
    /// Entry and payload byte limits shared by all sessions receiving messages; unread messages from old sessions still occupy the quota.
    pub incoming: QueueLimit,
    /// The maximum number of message subscriptions that a client can hold at the same time.
    pub message_subscriptions: usize,
    /// The maximum number of deliveries that can be held simultaneously when a message is distributed to subscribers; multiple recipients of the same message are counted separately.
    pub message_deliveries: usize,
    /// The upper limit on the number of tasks that message callbacks can perform concurrently; worker threads are created on demand.
    pub message_callback_workers: usize,
    /// The maximum number of connection state subscriptions a client can hold simultaneously.
    pub state_subscriptions: usize,
    /// Number of worker threads to execute connection status callbacks, allowed range is 1 to 256.
    pub state_callback_workers: usize,
    /// The maximum number of connection event subscriptions that a client can hold simultaneously.
    pub event_subscriptions: usize,
    /// Number of worker threads to execute connection event callbacks, allowed range is 1 to 256.
    pub event_callback_workers: usize,
    /// The upper limit of the number of task final event subscriptions that the client can hold at the same time.
    pub task_subscriptions: usize,
    /// The number of worker threads that execute task final event callbacks. The allowed range is 1 to 256.
    pub task_callback_workers: usize,
    /// Shared limits for final-state notifications from all session tasks;
    /// quotas are reserved when a task is admitted and count both deliveries
    /// and payload bytes.
    pub task_events: QueueLimit,
    /// The maximum number of tasks that can be executed simultaneously on a blocking handshake context provider.
    pub blocking_handshake_jobs: usize,
}

impl Default for DispatchLimits {
    fn default() -> Self {
        Self {
            incoming: QueueLimit {
                max_items: 256,
                max_bytes: 64 * 1024 * 1024,
            },
            message_subscriptions: 64,
            message_deliveries: 1024,
            message_callback_workers: 1,
            state_subscriptions: 64,
            state_callback_workers: 2,
            event_subscriptions: 64,
            event_callback_workers: 2,
            task_subscriptions: 64,
            task_callback_workers: 2,
            task_events: QueueLimit {
                max_items: 1024,
                max_bytes: 16 * 1024 * 1024,
            },
            blocking_handshake_jobs: 8,
        }
    }
}

impl DispatchLimits {
    /// Validates distribution quotas and callback worker counts.
    pub fn validate(&self) -> Result<()> {
        self.incoming
            .validate_fields("dispatch.incoming.max_items", "dispatch.incoming.max_bytes")?;
        for (value, field) in [
            (self.message_subscriptions, "dispatch.message_subscriptions"),
            (self.message_deliveries, "dispatch.message_deliveries"),
            (
                self.message_callback_workers,
                "dispatch.message_callback_workers",
            ),
            (self.state_subscriptions, "dispatch.state_subscriptions"),
            (self.event_subscriptions, "dispatch.event_subscriptions"),
            (self.task_subscriptions, "dispatch.task_subscriptions"),
            (
                self.blocking_handshake_jobs,
                "dispatch.blocking_handshake_jobs",
            ),
        ] {
            permits(value, field)?;
        }
        for (value, field) in [
            (
                self.state_callback_workers,
                "dispatch.state_callback_workers",
            ),
            (
                self.event_callback_workers,
                "dispatch.event_callback_workers",
            ),
            (self.task_callback_workers, "dispatch.task_callback_workers"),
        ] {
            if value == 0 || value > MAX_FIXED_CALLBACK_WORKERS {
                return Err(NetError::config(field, "must be between 1 and 256"));
            }
        }
        self.task_events.validate_fields(
            "dispatch.task_events.max_items",
            "dispatch.task_events.max_bytes",
        )
    }
}

/// Request registration capacity and manual processing grace configuration of received responses.
#[derive(Clone, Debug)]
pub struct RequestLimits {
    /// Maximum number of requests that may be registered and unfinished at one
    /// time; the default is 4,096.
    pub max_pending: usize,
    /// Processing grace reserved for responses received in time but not yet manually parsed, default 2 seconds; zero means no wait.
    ///
    /// Grace does not extend the absolute deadline of the request and is also used to wait for the response callback to drain when the connection is terminated.
    pub manual_response_grace: Duration,
}

impl Default for RequestLimits {
    fn default() -> Self {
        Self {
            max_pending: 4096,
            manual_response_grace: Duration::from_secs(2),
        }
    }
}

impl RequestLimits {
    /// Validates pending-request capacity and manual response grace.
    pub fn validate(&self) -> Result<()> {
        permits(self.max_pending, "requests.max_pending")?;
        deadline(
            self.manual_response_grace,
            "requests.manual_response_grace",
            true,
        )
    }
}

/// WebSocket data frame fragmentation, read and write buffers, and receive size limits.
#[derive(Clone, Debug)]
pub struct FrameConfig {
    /// Payload size, in bytes, for outgoing data-frame fragments; the default is
    /// 32 KiB and `None` disables active fragmentation.
    /// Set to at least 1024 bytes, and the write buffer limit must also accommodate the payload and frame header.
    /// Control frames can be scheduled between fragments, but cannot pre-empt an
    /// in-progress frame or overtake bytes already buffered by the transport.
    /// This setting does not split one logical message into multiple messages,
    /// and does not control the peer's outgoing frame sizes.
    pub data_frame_payload_size: Option<usize>,
    /// Maximum time for a single Ping, Pong, or Close write and for closing the
    /// underlying sender; the default is 1,500 milliseconds.
    /// This bounds the local write operation, including any preceding buffered
    /// data it must drain; it is not an end-to-end peer response deadline.
    pub control_write_timeout: Duration,
    /// The time limit for writing a single data frame, the default is 1500 milliseconds; it is still subject to the overall message writing deadline.
    /// Deferred data batches retain the earliest pending frame's deadline.
    /// Expiry after a write has started retires the connection because delivery
    /// may be partial; it does not imply a missing heartbeat Pong.
    pub data_frame_write_timeout: Duration,
    /// The underlying WebSocket read buffer size in bytes, default 128 KiB.
    pub read_buffer_size: usize,
    /// Target size of the underlying WebSocket write buffer, in bytes, defaults to 128 KiB; zero is allowed.
    pub write_buffer_size: usize,
    /// Maximum number of bytes for the underlying WebSocket write buffer, defaults to 4 MiB; must be larger than the target write buffer size.
    pub max_write_buffer_size: usize,
    /// The maximum number of bytes to receive a complete message, default 64 MiB; `None` means not to set this size limit.
    pub max_message_size: Option<usize>,
    /// Maximum bytes in one received frame; the default is 16 MiB and `None`
    /// disables this limit.
    pub max_frame_size: Option<usize>,
}

impl Default for FrameConfig {
    fn default() -> Self {
        Self {
            data_frame_payload_size: Some(Self::DEFAULT_DATA_FRAME_PAYLOAD_SIZE),
            control_write_timeout: Duration::from_millis(1500),
            data_frame_write_timeout: Duration::from_millis(1500),
            read_buffer_size: 128 * 1024,
            write_buffer_size: 128 * 1024,
            max_write_buffer_size: 4 * 1024 * 1024,
            max_message_size: Some(64 * 1024 * 1024),
            max_frame_size: Some(16 * 1024 * 1024),
        }
    }
}

impl FrameConfig {
    /// Smallest supported outgoing data-frame payload fragment.
    pub const MIN_DATA_FRAME_PAYLOAD_SIZE: usize = 1024;
    /// Default outgoing data-frame payload fragment size.
    pub const DEFAULT_DATA_FRAME_PAYLOAD_SIZE: usize = 32 * 1024;
    pub(crate) const MAX_CLIENT_FRAME_OVERHEAD: usize = 14;

    /// Validates frame sizes, buffer capacities, and write deadlines.
    pub fn validate(&self) -> Result<()> {
        deadline(
            self.control_write_timeout,
            "frames.control_write_timeout",
            false,
        )?;
        deadline(
            self.data_frame_write_timeout,
            "frames.data_frame_write_timeout",
            false,
        )?;
        allocation_size(self.read_buffer_size, "frames.read_buffer_size", false)?;
        allocation_size(self.write_buffer_size, "frames.write_buffer_size", true)?;
        allocation_size(
            self.max_write_buffer_size,
            "frames.max_write_buffer_size",
            false,
        )?;
        if self.max_write_buffer_size <= self.write_buffer_size {
            return Err(NetError::config(
                "frames.max_write_buffer_size",
                "must exceed frames.write_buffer_size",
            ));
        }
        for (limit, field) in [
            (self.max_message_size, "frames.max_message_size"),
            (self.max_frame_size, "frames.max_frame_size"),
        ] {
            if let Some(size) = limit {
                allocation_size(size, field, false)?;
            }
        }
        if let Some(size) = self.data_frame_payload_size {
            if size < Self::MIN_DATA_FRAME_PAYLOAD_SIZE
                || size
                    .checked_add(Self::MAX_CLIENT_FRAME_OVERHEAD)
                    .is_none_or(|size| size > isize::MAX as usize)
            {
                return Err(NetError::config("frames.data_frame_payload_size", "must be at least 1024 bytes and leave room for the frame header within isize::MAX"));
            }
            self.validate_outgoing_payload(size)?;
        }
        Ok(())
    }

    fn validate_outgoing_payload(&self, payload: usize) -> Result<()> {
        match payload.checked_add(Self::MAX_CLIENT_FRAME_OVERHEAD) {
            Some(required) if required <= self.max_write_buffer_size => Ok(()),
            _ => Err(NetError::config(
                "frames.max_write_buffer_size",
                "must hold one outgoing frame payload and its 14-byte header",
            )),
        }
    }
}

/// Socket configuration for the underlying WebSocket TCP connection.
#[derive(Clone, Debug)]
pub struct TcpConfig {
    /// Whether to enable `TCP_NODELAY` to disable Nagle algorithm, default `true`.
    pub nodelay: bool,
    /// Request to set the TCP send buffer size in bytes; `None` means to keep the system default value.
    pub send_buffer_size: Option<usize>,
    /// TCP keepalive detection parameters; `None` means no additional configuration of TCP keepalive.
    pub keepalive: Option<TcpKeepaliveConfig>,
}

impl Default for TcpConfig {
    fn default() -> Self {
        Self {
            nodelay: true,
            send_buffer_size: None,
            keepalive: None,
        }
    }
}

impl TcpConfig {
    /// Validates native socket buffer and keepalive settings.
    pub fn validate(&self) -> Result<()> {
        if let Some(size) = self.send_buffer_size {
            if size == 0 || size > i32::MAX as usize {
                return Err(NetError::config(
                    "tcp.send_buffer_size",
                    "must be between 1 and i32::MAX for the native socket option",
                ));
            }
        }
        if let Some(keepalive) = &self.keepalive {
            keepalive.validate()?;
        }
        Ok(())
    }
}

/// Idle wait time and probe interval for TCP keepalive probes; specific support depends on the running platform.
#[derive(Clone, Debug)]
pub struct TcpKeepaliveConfig {
    /// How long after the connection is idle before sending keepalive probes, the default is 5 seconds.
    pub idle: Duration,
    /// The time interval between consecutive keepalive probes, default 2 seconds.
    pub interval: Duration,
}

impl Default for TcpKeepaliveConfig {
    fn default() -> Self {
        Self {
            idle: Duration::from_secs(5),
            interval: Duration::from_secs(2),
        }
    }
}

impl TcpKeepaliveConfig {
    /// Validates non-zero keepalive durations and platform-native ranges.
    pub fn validate(&self) -> Result<()> {
        nonzero_duration(self.idle, "tcp.keepalive.idle")?;
        nonzero_duration(self.interval, "tcp.keepalive.interval")?;
        // Match socket2's actual option conversion on each target. Unsupported
        // options must not acquire artificial native range restrictions.
        #[cfg(windows)]
        {
            native_keepalive_duration(self.idle, "tcp.keepalive.idle")?;
            native_keepalive_duration(self.interval, "tcp.keepalive.interval")?;
        }
        #[cfg(all(
            unix,
            not(any(
                target_os = "haiku",
                target_os = "openbsd",
                target_os = "nto",
                target_os = "vita"
            ))
        ))]
        native_keepalive_duration(self.idle, "tcp.keepalive.idle")?;
        #[cfg(any(
            target_os = "aix",
            target_os = "android",
            target_os = "dragonfly",
            target_os = "emscripten",
            target_os = "freebsd",
            target_os = "fuchsia",
            target_os = "hurd",
            target_os = "illumos",
            target_os = "ios",
            target_os = "visionos",
            target_os = "linux",
            target_os = "macos",
            target_os = "netbsd",
            target_os = "tvos",
            target_os = "watchos",
            target_os = "cygwin",
            target_os = "nuttx",
            all(target_os = "wasi", not(target_env = "p1"))
        ))]
        native_keepalive_duration(self.interval, "tcp.keepalive.interval")?;
        Ok(())
    }
}

/// Active Ping/Pong heartbeat parameters on each physical connection.
#[derive(Clone, Debug)]
pub struct HeartbeatConfig {
    /// Interval for checking whether to send a heartbeat Ping; the default is
    /// 20 seconds. No new probe is created while another Ping is pending.
    pub interval: Duration,
    /// The time limit for waiting for a matching Pong after the local Ping write
    /// succeeds. The default is 45 seconds.
    ///
    /// Local write completion does not mean the peer has received the Ping:
    /// TCP/TLS buffering, network delay, peer processing, and local receive
    /// scheduling can consume this budget. A responsive peer can still exceed
    /// a short deadline under load. The deadline is not extended by unrelated
    /// traffic or by a late matching Pong.
    pub pong_timeout: Duration,
    /// Bounded recovery and safe Ping-write retry policy. The default keeps the
    /// existing fail-fast behavior by disabling both retry paths.
    pub retry: HeartbeatRetryConfig,
}

impl Default for HeartbeatConfig {
    fn default() -> Self {
        Self {
            interval: Duration::from_secs(20),
            pong_timeout: Duration::from_secs(45),
            retry: HeartbeatRetryConfig::default(),
        }
    }
}

impl HeartbeatConfig {
    /// Validates heartbeat intervals and Pong deadlines.
    pub fn validate(&self) -> Result<()> {
        deadline(self.interval, "heartbeat.interval", false)?;
        deadline(self.pong_timeout, "heartbeat.pong_timeout", false)?;
        self.retry.validate()
    }
}

/// Bounded recovery policy for WebSocket control-layer heartbeats.
///
/// `pong_recovery_attempts` counts the additional Ping probes after the
/// normal probe's Pong deadline expires and is limited to ten. `ping_write_retries`
/// counts only additional safe write attempts after the initial normal-heartbeat write.
/// A write timeout or an error with unknown delivery is never retried on the
/// same sink; the physical connection is retired instead.
#[derive(Clone, Debug)]
pub struct HeartbeatRetryConfig {
    /// Number of additional fast Ping probes after a Pong timeout.
    pub pong_recovery_attempts: usize,
    /// Maximum wait for a matching Pong for each recovery probe and the delay
    /// before the next probe.
    pub pong_retry_interval: Duration,
    /// Number of additional normal-heartbeat Ping write attempts.
    pub ping_write_retries: usize,
    /// Delay between safe normal-heartbeat Ping write attempts.
    pub ping_write_retry_interval: Duration,
}

impl Default for HeartbeatRetryConfig {
    fn default() -> Self {
        Self {
            pong_recovery_attempts: 0,
            pong_retry_interval: Duration::from_millis(1500),
            ping_write_retries: 0,
            ping_write_retry_interval: Duration::from_millis(1500),
        }
    }
}

impl HeartbeatRetryConfig {
    /// Validates retry counts and enabled retry delays without permitting a
    /// busy loop or an unrepresentable monotonic deadline.
    pub fn validate(&self) -> Result<()> {
        self.validate_attempts(
            self.pong_recovery_attempts,
            self.pong_retry_interval,
            "heartbeat.retry.pong_recovery_attempts",
            "heartbeat.retry.pong_retry_interval",
            MAX_HEARTBEAT_PONG_RECOVERY_ATTEMPTS,
        )?;
        self.validate_attempts(
            self.ping_write_retries,
            self.ping_write_retry_interval,
            "heartbeat.retry.ping_write_retries",
            "heartbeat.retry.ping_write_retry_interval",
            MAX_HEARTBEAT_PING_WRITE_RETRIES,
        )
    }

    fn validate_attempts(
        &self,
        attempts: usize,
        interval: Duration,
        attempts_field: &str,
        interval_field: &str,
        maximum: usize,
    ) -> Result<()> {
        if attempts == 0 {
            return Ok(());
        }
        if attempts > maximum {
            return Err(NetError::config(
                attempts_field,
                format!("must not exceed {maximum}"),
            ));
        }
        deadline(interval, interval_field, false)
    }
}

fn positive(value: usize, field: &str) -> Result<()> {
    if value == 0 {
        Err(NetError::config(field, "must be greater than zero"))
    } else {
        Ok(())
    }
}

fn permits(value: usize, field: &str) -> Result<()> {
    positive(value, field)?;
    if value > Semaphore::MAX_PERMITS {
        Err(NetError::config(
            field,
            "must not exceed Tokio Semaphore::MAX_PERMITS",
        ))
    } else {
        Ok(())
    }
}

fn allocation_size(value: usize, field: &str, allow_zero: bool) -> Result<()> {
    if !allow_zero {
        positive(value, field)?;
    }
    if value > isize::MAX as usize {
        Err(NetError::config(
            field,
            "must not exceed isize::MAX for a byte allocation",
        ))
    } else {
        Ok(())
    }
}

fn nonzero_duration(value: Duration, field: &str) -> Result<()> {
    if value.is_zero() {
        Err(NetError::config(field, "must be greater than zero"))
    } else {
        Ok(())
    }
}

pub(super) fn deadline(value: Duration, field: &str, allow_zero: bool) -> Result<()> {
    if !allow_zero {
        nonzero_duration(value, field)?;
    }
    if Instant::now().checked_add(value).is_none() {
        Err(NetError::config(
            field,
            "must fit a monotonic Instant deadline",
        ))
    } else {
        Ok(())
    }
}

#[cfg(windows)]
fn native_keepalive_duration(value: Duration, field: &str) -> Result<()> {
    if value.as_millis() == 0 || value.as_millis() >= u32::MAX as u128 {
        Err(NetError::config(
            field,
            "must be at least one millisecond and below u32::MAX milliseconds",
        ))
    } else {
        Ok(())
    }
}

#[cfg(not(windows))]
fn native_keepalive_duration(value: Duration, field: &str) -> Result<()> {
    if value.as_secs() == 0 || value.as_secs() > i32::MAX as u64 {
        Err(NetError::config(
            field,
            "must be at least one second and fit i32 seconds",
        ))
    } else {
        Ok(())
    }
}

#[cfg(test)]
#[path = "config_tests.rs"]
mod tests;