Skip to main content

open_net/api/ws/
receive_options.rs

1use super::QueueLimit;
2use crate::error::NetError;
3use crate::Result;
4
5/// Capacity and receive policy for one message subscription or initial inbox.
6#[derive(Clone, Debug)]
7pub struct ReceiveOptions {
8    /// Maximum queued messages (256 by default).
9    pub max_messages: usize,
10    /// Maximum total payload bytes (64 MiB by default).
11    pub max_bytes: usize,
12    /// Policy used when a message cannot enter the queue.
13    pub overflow: ReceiveOverflow,
14    /// Whether Ping, Pong, and Close frames are delivered (default `false`).
15    pub include_control_frames: bool,
16}
17
18impl Default for ReceiveOptions {
19    fn default() -> Self {
20        Self {
21            max_messages: 256,
22            max_bytes: 64 * 1024 * 1024,
23            overflow: ReceiveOverflow::Disconnect,
24            include_control_frames: false,
25        }
26    }
27}
28
29impl ReceiveOptions {
30    /// Validates queue item and byte limits.
31    pub fn validate(&self) -> Result<()> {
32        QueueLimit {
33            max_items: self.max_messages,
34            max_bytes: self.max_bytes,
35        }
36        .validate_fields("receive.max_messages", "receive.max_bytes")
37    }
38}
39
40/// Behavior when a message subscription reaches capacity.
41#[derive(Clone, Copy, Debug, Eq, PartialEq)]
42pub enum ReceiveOverflow {
43    /// Report overflow and disconnect the current connection.
44    Disconnect,
45    /// Drop the oldest queued message to make room for the new one.
46    DropOldest,
47}
48
49/// Capacity for connection-event history or one event subscription.
50#[derive(Clone, Debug)]
51pub struct EventOptions {
52    /// Maximum retained events (32 by default).
53    pub max_events: usize,
54    /// Maximum accounted bytes (1 MiB by default).
55    pub max_bytes: usize,
56}
57
58impl Default for EventOptions {
59    fn default() -> Self {
60        Self {
61            max_events: 32,
62            max_bytes: 1024 * 1024,
63        }
64    }
65}
66
67impl EventOptions {
68    /// Validates event count and byte limits.
69    pub fn validate(&self) -> Result<()> {
70        QueueLimit {
71            max_items: self.max_events,
72            max_bytes: self.max_bytes,
73        }
74        .validate_fields("events.max_events", "events.max_bytes")
75    }
76}
77
78/// Reserved capacity for one terminal task-event subscription.
79#[derive(Clone, Debug)]
80pub struct TaskEventOptions {
81    /// Maximum reserved terminal notifications (1024 by default).
82    pub max_tasks: usize,
83    /// Maximum total bytes for associated payloads (16 MiB by default).
84    pub max_payload_bytes: usize,
85    /// Capacity reserved for the urgent lane; `None` shares all capacity between lanes.
86    /// When set, positive item and byte capacity must remain for normal tasks.
87    pub urgent_reserve: Option<QueueLimit>,
88}
89
90impl Default for TaskEventOptions {
91    fn default() -> Self {
92        Self {
93            max_tasks: 1024,
94            max_payload_bytes: 16 * 1024 * 1024,
95            urgent_reserve: None,
96        }
97    }
98}
99
100impl TaskEventOptions {
101    /// Validates total capacity and urgent-lane reservations.
102    pub fn validate(&self) -> Result<()> {
103        QueueLimit {
104            max_items: self.max_tasks,
105            max_bytes: self.max_payload_bytes,
106        }
107        .validate_fields("task_events.max_tasks", "task_events.max_payload_bytes")?;
108        if let Some(urgent) = &self.urgent_reserve {
109            urgent.validate_fields(
110                "task_events.urgent_reserve.max_items",
111                "task_events.urgent_reserve.max_bytes",
112            )?;
113            if urgent.max_items >= self.max_tasks {
114                return Err(NetError::config(
115                    "task_events.urgent_reserve.max_items",
116                    "must leave positive capacity for normal tasks within max_tasks",
117                ));
118            }
119            if urgent.max_bytes >= self.max_payload_bytes {
120                return Err(NetError::config(
121                    "task_events.urgent_reserve.max_bytes",
122                    "must leave positive capacity for normal tasks within max_payload_bytes",
123                ));
124            }
125        }
126        Ok(())
127    }
128}