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
use super::config::deadline;
use super::WsSendRetryPolicy;
use super::{validate_metadata, CancellationGroup};
use crate::api::retry::RetrySetting;
use crate::{Metadata, NetError, Result};
use std::fmt;
use std::time::{Duration, Instant};
/// Scheduling, cancellation, retry, and per-stage deadline configuration for
/// one outbound message.
///
/// `Debug` includes scheduling configuration but reports metadata only as an entry count.
#[derive(Clone)]
pub struct SendOptions {
/// The normal or emergency sending channel used by the message. The default is the normal channel.
pub lane: MessageLane,
/// The scheduling priority within the normal channel; the emergency channel only accepts `Normal`.
pub priority: Priority,
/// Maximum time from the builder's first admission attempt until queue
/// resources are acquired; `None` imposes no separate admission limit.
/// Repeated admission attempts for the same builder use the original start
/// point, while the overall deadline remains in force.
pub enqueue_timeout: Option<Duration>,
/// The overall time limit for each actual write attempt, covering all shards of the message, defaults to 10 seconds.
pub write_timeout: Duration,
/// The original absolute deadline covering all stages, including queuing and reconnection waiting; `None` means there is no overall deadline.
pub deadline: Option<Instant>,
/// Retry permission after delivery failure; no retry by default. When retrying is allowed, the application must ensure the safety of repeated delivery.
pub retry_setting: RetrySetting<WsSendRetryPolicy>,
/// How to handle cases where the connection is not connected during admission or the connection is interrupted during waiting. The default is to reject the request.
pub disconnected: DisconnectedPolicy,
/// A cancellation group that can uniformly cancel a group of operations; `None` means not to join the cancellation group.
pub cancellation: Option<CancellationGroup>,
/// Local application metadata attached to the send operation; it is not
/// automatically added to the wire message payload.
pub metadata: Metadata,
}
impl fmt::Debug for SendOptions {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("SendOptions")
.field("lane", &self.lane)
.field("priority", &self.priority)
.field("enqueue_timeout", &self.enqueue_timeout)
.field("write_timeout", &self.write_timeout)
.field("deadline", &self.deadline)
.field("retry_setting", &self.retry_setting)
.field("disconnected", &self.disconnected)
.field("cancellation", &self.cancellation)
.field("metadata_entries", &self.metadata.len())
.finish()
}
}
impl Default for SendOptions {
fn default() -> Self {
Self {
lane: MessageLane::default(),
priority: Priority::default(),
enqueue_timeout: None,
write_timeout: Duration::from_secs(10),
deadline: None,
retry_setting: RetrySetting::Inherit,
disconnected: DisconnectedPolicy::default(),
cancellation: None,
metadata: Metadata::new(),
}
}
}
impl SendOptions {
/// Checks configuration without starting timers or changing the deadline.
///
/// A zero timeout or an elapsed absolute deadline represents an immediate
/// operational timeout, rather than an invalid configuration.
pub fn validate(&self) -> Result<()> {
if self.lane == MessageLane::Urgent && self.priority != Priority::Normal {
return Err(NetError::config(
"priority",
"must be Normal for the Urgent lane",
));
}
if let Some(timeout) = self.enqueue_timeout {
deadline(timeout, "enqueue_timeout", true)?;
}
deadline(self.write_timeout, "write_timeout", true)?;
validate_metadata(&self.metadata)
}
}
/// Send queue channel; ordinary and emergency lanes have independent capacities.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub enum MessageLane {
/// The ordinary sending channel supports scheduling by priority and is the only channel allowed for tracked requests.
#[default]
Normal,
/// The emergency sending channel uses an independent queue and is processed first at the sending scheduling boundary.
Urgent,
}
/// The message scheduling priority in the ordinary sending channel.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub enum Priority {
/// Low priority.
Low,
/// Normal priority is also the default value and the value required for emergency channels.
#[default]
Normal,
/// High priority.
High,
}
/// Policy for a message that has not started sending when the session is
/// disconnected or becomes disconnected.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub enum DisconnectedPolicy {
/// Only accepts the currently connected connection generation; fails the operation if it is not connected or the connection ends.
#[default]
Reject,
/// Allow an unsent message to wait for session reconnection, subject to its
/// cancellation and deadline limits.
WaitForReconnect,
}
/// The sending, registration, and response wait limits for a tracked request.
#[derive(Clone, Debug)]
pub struct RequestOptions {
/// Request message sending configuration; requests can only use normal sending channels.
pub send: SendOptions,
/// Time limit to wait for a response from the selected starting point, default 30 seconds; zero means immediate expiration.
pub response_timeout: Duration,
/// Point at which response waiting begins; the default is after the request
/// has been written successfully.
pub response_timeout_origin: ResponseTimeoutOrigin,
/// The absolute deadline for completing the requested registration; `None` means not to limit the registration phase individually.
/// This restriction is no longer used after registration is completed, and `send.deadline` still binds the entire request.
pub registration_deadline: Option<Instant>,
}
impl Default for RequestOptions {
fn default() -> Self {
Self {
send: SendOptions::default(),
response_timeout: Duration::from_secs(30),
response_timeout_origin: ResponseTimeoutOrigin::default(),
registration_deadline: None,
}
}
}
impl RequestOptions {
/// Checks options while retaining the caller's original absolute deadlines.
pub fn validate(&self) -> Result<()> {
if self.send.lane != MessageLane::Normal {
return Err(NetError::config(
"send.lane",
"tracked requests require the Normal lane",
));
}
self.send.validate().map_err(|error| {
if let Some(detail) = error.config_error() {
NetError::config(format!("send.{}", detail.field()), detail.reason())
} else {
error
}
})?;
deadline(self.response_timeout, "response_timeout", true)
}
}
/// Point at which the response-wait timeout starts.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub enum ResponseTimeoutOrigin {
/// Start timing when registration completes, so the timeout includes later
/// queueing and send time.
Registered,
/// Start timing after the request message is written successfully; time
/// spent registering, queueing, and writing is excluded from this timeout.
#[default]
Written,
}