1#![forbid(unsafe_code)]
8#![warn(missing_docs)]
9
10use std::error::Error;
11use std::fmt;
12
13#[derive(Debug, Clone, PartialEq, Eq)]
15pub struct Envelope<T> {
16 id: String,
17 payload: T,
18 created_at_ms: u64,
19 expires_at_ms: u64,
20}
21
22impl<T> Envelope<T> {
23 pub fn new(
28 id: impl Into<String>,
29 payload: T,
30 created_at_ms: u64,
31 ttl_ms: u64,
32 ) -> Result<Self, ProtocolError> {
33 let id = id.into();
34 if id.trim().is_empty() {
35 return Err(ProtocolError::EmptyMessageId);
36 }
37 if ttl_ms == 0 {
38 return Err(ProtocolError::ZeroTimeToLive);
39 }
40 let expires_at_ms = created_at_ms
41 .checked_add(ttl_ms)
42 .ok_or(ProtocolError::TimeOverflow)?;
43 Ok(Self {
44 id,
45 payload,
46 created_at_ms,
47 expires_at_ms,
48 })
49 }
50
51 pub fn id(&self) -> &str {
53 &self.id
54 }
55
56 pub const fn payload(&self) -> &T {
58 &self.payload
59 }
60
61 pub const fn created_at_ms(&self) -> u64 {
63 self.created_at_ms
64 }
65
66 pub const fn expires_at_ms(&self) -> u64 {
68 self.expires_at_ms
69 }
70
71 pub fn into_payload(self) -> T {
73 self.payload
74 }
75}
76
77#[derive(Debug, Clone, Copy, PartialEq, Eq)]
79pub struct DeliveryPolicy {
80 acknowledgement_timeout_ms: u64,
81 max_attempts: u32,
82}
83
84impl DeliveryPolicy {
85 pub fn new(acknowledgement_timeout_ms: u64, max_attempts: u32) -> Result<Self, ProtocolError> {
87 if acknowledgement_timeout_ms == 0 {
88 return Err(ProtocolError::ZeroAcknowledgementTimeout);
89 }
90 if max_attempts == 0 {
91 return Err(ProtocolError::ZeroMaxAttempts);
92 }
93 Ok(Self {
94 acknowledgement_timeout_ms,
95 max_attempts,
96 })
97 }
98
99 pub const fn acknowledgement_timeout_ms(self) -> u64 {
101 self.acknowledgement_timeout_ms
102 }
103
104 pub const fn max_attempts(self) -> u32 {
106 self.max_attempts
107 }
108}
109
110#[derive(Debug, Clone, Copy, PartialEq, Eq)]
112pub enum DeliveryState {
113 Ready,
115 AwaitingAcknowledgement {
117 sent_at_ms: u64,
119 retry_at_ms: u64,
121 },
122 Delivered {
124 acknowledged_at_ms: u64,
126 },
127 Expired {
129 observed_at_ms: u64,
131 },
132 Exhausted {
134 observed_at_ms: u64,
136 },
137}
138
139#[derive(Debug, Clone, Copy, PartialEq, Eq)]
141pub enum DeliveryOutcome {
142 Delivered,
144 Expired,
146 Exhausted,
148}
149
150#[derive(Debug, Clone, Copy, PartialEq, Eq)]
152pub enum NextAction {
153 SendNow {
155 attempt: u32,
157 },
158 WaitUntil(u64),
160 Complete(DeliveryOutcome),
162}
163
164#[derive(Debug, Clone, Copy, PartialEq, Eq)]
166pub enum AckResult {
167 Accepted,
169 Duplicate,
171}
172
173#[derive(Debug, Clone, PartialEq, Eq)]
175pub struct Delivery<T> {
176 envelope: Envelope<T>,
177 policy: DeliveryPolicy,
178 state: DeliveryState,
179 attempts: u32,
180 last_observed_ms: u64,
181}
182
183impl<T> Delivery<T> {
184 pub const fn new(envelope: Envelope<T>, policy: DeliveryPolicy) -> Self {
186 let last_observed_ms = envelope.created_at_ms;
187 Self {
188 envelope,
189 policy,
190 state: DeliveryState::Ready,
191 attempts: 0,
192 last_observed_ms,
193 }
194 }
195
196 pub const fn envelope(&self) -> &Envelope<T> {
198 &self.envelope
199 }
200
201 pub const fn policy(&self) -> DeliveryPolicy {
203 self.policy
204 }
205
206 pub const fn state(&self) -> DeliveryState {
208 self.state
209 }
210
211 pub const fn attempts(&self) -> u32 {
213 self.attempts
214 }
215
216 pub fn poll(&mut self, now_ms: u64) -> Result<NextAction, ProtocolError> {
218 self.observe(now_ms)?;
219
220 if let Some(outcome) = terminal_outcome(self.state) {
221 return Ok(NextAction::Complete(outcome));
222 }
223 if self.expire_if_due(now_ms) {
224 return Ok(NextAction::Complete(DeliveryOutcome::Expired));
225 }
226
227 match self.state {
228 DeliveryState::Ready => self.ready_action(now_ms),
229 DeliveryState::AwaitingAcknowledgement { retry_at_ms, .. } => {
230 if now_ms < retry_at_ms {
231 Ok(NextAction::WaitUntil(
232 retry_at_ms.min(self.envelope.expires_at_ms),
233 ))
234 } else if self.attempts < self.policy.max_attempts {
235 self.state = DeliveryState::Ready;
236 self.ready_action(now_ms)
237 } else {
238 self.state = DeliveryState::Exhausted {
239 observed_at_ms: now_ms,
240 };
241 Ok(NextAction::Complete(DeliveryOutcome::Exhausted))
242 }
243 }
244 DeliveryState::Delivered { .. }
245 | DeliveryState::Expired { .. }
246 | DeliveryState::Exhausted { .. } => unreachable!("terminal states handled above"),
247 }
248 }
249
250 pub fn record_sent(&mut self, now_ms: u64) -> Result<(), ProtocolError> {
252 self.observe(now_ms)?;
253 if terminal_outcome(self.state).is_some() {
254 return Err(ProtocolError::DeliveryAlreadyTerminal);
255 }
256 if self.expire_if_due(now_ms) {
257 return Err(ProtocolError::DeliveryAlreadyTerminal);
258 }
259 if self.state != DeliveryState::Ready {
260 return Err(ProtocolError::SendAlreadyAwaitingAcknowledgement);
261 }
262 if self.attempts >= self.policy.max_attempts {
263 self.state = DeliveryState::Exhausted {
264 observed_at_ms: now_ms,
265 };
266 return Err(ProtocolError::AttemptsExhausted);
267 }
268
269 let retry_at_ms = now_ms
270 .checked_add(self.policy.acknowledgement_timeout_ms)
271 .ok_or(ProtocolError::TimeOverflow)?;
272 self.attempts += 1;
273 self.state = DeliveryState::AwaitingAcknowledgement {
274 sent_at_ms: now_ms,
275 retry_at_ms,
276 };
277 Ok(())
278 }
279
280 pub fn acknowledge(&mut self, now_ms: u64) -> Result<AckResult, ProtocolError> {
282 self.observe(now_ms)?;
283 if matches!(self.state, DeliveryState::Delivered { .. }) {
284 return Ok(AckResult::Duplicate);
285 }
286 if terminal_outcome(self.state).is_some() {
287 return Err(ProtocolError::DeliveryAlreadyTerminal);
288 }
289 if self.expire_if_due(now_ms) {
290 return Err(ProtocolError::DeliveryAlreadyTerminal);
291 }
292
293 if matches!(self.state, DeliveryState::AwaitingAcknowledgement { .. }) {
294 self.state = DeliveryState::Delivered {
295 acknowledged_at_ms: now_ms,
296 };
297 Ok(AckResult::Accepted)
298 } else {
299 Err(ProtocolError::UnexpectedAcknowledgement)
300 }
301 }
302
303 fn ready_action(&mut self, now_ms: u64) -> Result<NextAction, ProtocolError> {
304 if self.attempts < self.policy.max_attempts {
305 Ok(NextAction::SendNow {
306 attempt: self.attempts + 1,
307 })
308 } else {
309 self.state = DeliveryState::Exhausted {
310 observed_at_ms: now_ms,
311 };
312 Ok(NextAction::Complete(DeliveryOutcome::Exhausted))
313 }
314 }
315
316 fn observe(&mut self, now_ms: u64) -> Result<(), ProtocolError> {
317 if now_ms < self.last_observed_ms {
318 return Err(ProtocolError::TimeMovedBackwards {
319 previous_ms: self.last_observed_ms,
320 supplied_ms: now_ms,
321 });
322 }
323 self.last_observed_ms = now_ms;
324 Ok(())
325 }
326
327 fn expire_if_due(&mut self, now_ms: u64) -> bool {
328 if now_ms >= self.envelope.expires_at_ms {
329 self.state = DeliveryState::Expired {
330 observed_at_ms: now_ms,
331 };
332 true
333 } else {
334 false
335 }
336 }
337}
338
339fn terminal_outcome(state: DeliveryState) -> Option<DeliveryOutcome> {
340 match state {
341 DeliveryState::Delivered { .. } => Some(DeliveryOutcome::Delivered),
342 DeliveryState::Expired { .. } => Some(DeliveryOutcome::Expired),
343 DeliveryState::Exhausted { .. } => Some(DeliveryOutcome::Exhausted),
344 DeliveryState::Ready | DeliveryState::AwaitingAcknowledgement { .. } => None,
345 }
346}
347
348#[derive(Debug, Clone, PartialEq, Eq)]
350pub enum ProtocolError {
351 EmptyMessageId,
353 ZeroTimeToLive,
355 ZeroAcknowledgementTimeout,
357 ZeroMaxAttempts,
359 TimeOverflow,
361 TimeMovedBackwards {
363 previous_ms: u64,
365 supplied_ms: u64,
367 },
368 SendAlreadyAwaitingAcknowledgement,
370 UnexpectedAcknowledgement,
372 DeliveryAlreadyTerminal,
374 AttemptsExhausted,
376}
377
378impl fmt::Display for ProtocolError {
379 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
380 match self {
381 Self::EmptyMessageId => formatter.write_str("message id must not be blank"),
382 Self::ZeroTimeToLive => formatter.write_str("time-to-live must be greater than zero"),
383 Self::ZeroAcknowledgementTimeout => {
384 formatter.write_str("acknowledgement timeout must be greater than zero")
385 }
386 Self::ZeroMaxAttempts => {
387 formatter.write_str("maximum attempts must be greater than zero")
388 }
389 Self::TimeOverflow => formatter.write_str("timestamp arithmetic overflowed"),
390 Self::TimeMovedBackwards {
391 previous_ms,
392 supplied_ms,
393 } => write!(
394 formatter,
395 "time moved backwards from {previous_ms} to {supplied_ms}"
396 ),
397 Self::SendAlreadyAwaitingAcknowledgement => {
398 formatter.write_str("a send is already awaiting acknowledgement")
399 }
400 Self::UnexpectedAcknowledgement => {
401 formatter.write_str("acknowledgement arrived before a send")
402 }
403 Self::DeliveryAlreadyTerminal => formatter.write_str("delivery is already terminal"),
404 Self::AttemptsExhausted => formatter.write_str("all send attempts are exhausted"),
405 }
406 }
407}
408
409impl Error for ProtocolError {}
410
411#[cfg(test)]
412mod tests {
413 use super::*;
414
415 fn delivery(ttl: u64, timeout: u64, attempts: u32) -> Delivery<&'static str> {
416 Delivery::new(
417 Envelope::new("message-1", "payload", 1_000, ttl).unwrap(),
418 DeliveryPolicy::new(timeout, attempts).unwrap(),
419 )
420 }
421
422 #[test]
423 fn ready_send_and_wait_are_explicit() {
424 let mut delivery = delivery(10_000, 500, 3);
425 assert_eq!(
426 delivery.poll(1_000).unwrap(),
427 NextAction::SendNow { attempt: 1 }
428 );
429 delivery.record_sent(1_000).unwrap();
430 assert_eq!(delivery.attempts(), 1);
431 assert_eq!(delivery.poll(1_200).unwrap(), NextAction::WaitUntil(1_500));
432 }
433
434 #[test]
435 fn timeout_enables_next_numbered_attempt() {
436 let mut delivery = delivery(10_000, 500, 3);
437 delivery.record_sent(1_000).unwrap();
438 assert_eq!(
439 delivery.poll(1_500).unwrap(),
440 NextAction::SendNow { attempt: 2 }
441 );
442 delivery.record_sent(1_500).unwrap();
443 assert_eq!(delivery.attempts(), 2);
444 }
445
446 #[test]
447 fn attempt_limit_terminates_delivery() {
448 let mut delivery = delivery(10_000, 100, 2);
449 delivery.record_sent(1_000).unwrap();
450 assert_eq!(
451 delivery.poll(1_100).unwrap(),
452 NextAction::SendNow { attempt: 2 }
453 );
454 delivery.record_sent(1_100).unwrap();
455 assert_eq!(
456 delivery.poll(1_200).unwrap(),
457 NextAction::Complete(DeliveryOutcome::Exhausted)
458 );
459 }
460
461 #[test]
462 fn expiry_has_priority_over_retry() {
463 let mut delivery = delivery(200, 500, 3);
464 delivery.record_sent(1_000).unwrap();
465 assert_eq!(
466 delivery.poll(1_200).unwrap(),
467 NextAction::Complete(DeliveryOutcome::Expired)
468 );
469 }
470
471 #[test]
472 fn duplicate_acknowledgement_is_idempotent() {
473 let mut delivery = delivery(10_000, 500, 3);
474 delivery.record_sent(1_000).unwrap();
475 assert_eq!(delivery.acknowledge(1_100).unwrap(), AckResult::Accepted);
476 assert_eq!(delivery.acknowledge(1_200).unwrap(), AckResult::Duplicate);
477 assert_eq!(
478 delivery.poll(20_000).unwrap(),
479 NextAction::Complete(DeliveryOutcome::Delivered)
480 );
481 }
482
483 #[test]
484 fn late_ack_before_envelope_expiry_is_accepted() {
485 let mut delivery = delivery(10_000, 100, 3);
486 delivery.record_sent(1_000).unwrap();
487 assert_eq!(delivery.acknowledge(1_500).unwrap(), AckResult::Accepted);
488 }
489
490 #[test]
491 fn invalid_transitions_are_rejected() {
492 let mut delivery = delivery(10_000, 500, 3);
493 assert_eq!(
494 delivery.acknowledge(1_000),
495 Err(ProtocolError::UnexpectedAcknowledgement)
496 );
497 delivery.record_sent(1_000).unwrap();
498 assert_eq!(
499 delivery.record_sent(1_001),
500 Err(ProtocolError::SendAlreadyAwaitingAcknowledgement)
501 );
502 }
503
504 #[test]
505 fn time_cannot_move_backwards() {
506 let mut delivery = delivery(10_000, 500, 3);
507 delivery.poll(1_100).unwrap();
508 assert_eq!(
509 delivery.poll(1_099),
510 Err(ProtocolError::TimeMovedBackwards {
511 previous_ms: 1_100,
512 supplied_ms: 1_099,
513 })
514 );
515 }
516
517 #[test]
518 fn invalid_configuration_is_rejected() {
519 assert_eq!(
520 Envelope::new(" ", (), 0, 1),
521 Err(ProtocolError::EmptyMessageId)
522 );
523 assert_eq!(
524 Envelope::new("id", (), 0, 0),
525 Err(ProtocolError::ZeroTimeToLive)
526 );
527 assert_eq!(
528 DeliveryPolicy::new(0, 1),
529 Err(ProtocolError::ZeroAcknowledgementTimeout)
530 );
531 assert_eq!(
532 DeliveryPolicy::new(1, 0),
533 Err(ProtocolError::ZeroMaxAttempts)
534 );
535 }
536}