Skip to main content

iei_protocol/
lib.rs

1//! A bounded, acknowledged delivery state machine.
2//!
3//! This crate deliberately leaves transport I/O to its caller. [`Delivery`]
4//! owns the protocol state and makes send, wait, retry, expiry, and completion
5//! decisions deterministic.
6
7#![forbid(unsafe_code)]
8#![warn(missing_docs)]
9
10use std::error::Error;
11use std::fmt;
12
13/// A payload with stable identity and a bounded lifetime.
14#[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    /// Creates an envelope.
24    ///
25    /// `ttl_ms` must be positive, the identifier must not be blank, and the
26    /// calculated expiry must fit in `u64`.
27    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    /// Returns the stable message identifier.
52    pub fn id(&self) -> &str {
53        &self.id
54    }
55
56    /// Returns the payload.
57    pub const fn payload(&self) -> &T {
58        &self.payload
59    }
60
61    /// Returns the creation timestamp in monotonic milliseconds.
62    pub const fn created_at_ms(&self) -> u64 {
63        self.created_at_ms
64    }
65
66    /// Returns the exclusive expiry boundary in monotonic milliseconds.
67    pub const fn expires_at_ms(&self) -> u64 {
68        self.expires_at_ms
69    }
70
71    /// Consumes the envelope and returns its payload.
72    pub fn into_payload(self) -> T {
73        self.payload
74    }
75}
76
77/// Retry limits for a delivery.
78#[derive(Debug, Clone, Copy, PartialEq, Eq)]
79pub struct DeliveryPolicy {
80    acknowledgement_timeout_ms: u64,
81    max_attempts: u32,
82}
83
84impl DeliveryPolicy {
85    /// Creates a policy with positive timeout and attempt count.
86    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    /// Returns acknowledgement timeout in milliseconds.
100    pub const fn acknowledgement_timeout_ms(self) -> u64 {
101        self.acknowledgement_timeout_ms
102    }
103
104    /// Returns the maximum number of send attempts.
105    pub const fn max_attempts(self) -> u32 {
106        self.max_attempts
107    }
108}
109
110/// Current protocol state.
111#[derive(Debug, Clone, Copy, PartialEq, Eq)]
112pub enum DeliveryState {
113    /// Ready for a first send or retry.
114    Ready,
115    /// A send was recorded and acknowledgement is pending.
116    AwaitingAcknowledgement {
117        /// Timestamp at which the current attempt was sent.
118        sent_at_ms: u64,
119        /// Timestamp at which this attempt becomes eligible for retry.
120        retry_at_ms: u64,
121    },
122    /// Acknowledgement was accepted.
123    Delivered {
124        /// Timestamp at which acknowledgement was accepted.
125        acknowledged_at_ms: u64,
126    },
127    /// The envelope reached its expiry boundary.
128    Expired {
129        /// Timestamp at which expiry was observed.
130        observed_at_ms: u64,
131    },
132    /// Every permitted attempt was used without acknowledgement.
133    Exhausted {
134        /// Timestamp at which exhaustion was observed.
135        observed_at_ms: u64,
136    },
137}
138
139/// Terminal result of a delivery.
140#[derive(Debug, Clone, Copy, PartialEq, Eq)]
141pub enum DeliveryOutcome {
142    /// Delivery was acknowledged.
143    Delivered,
144    /// The envelope expired.
145    Expired,
146    /// The retry limit was exhausted.
147    Exhausted,
148}
149
150/// Instruction returned by [`Delivery::poll`].
151#[derive(Debug, Clone, Copy, PartialEq, Eq)]
152pub enum NextAction {
153    /// The caller should make this numbered send attempt now.
154    SendNow {
155        /// One-based attempt number.
156        attempt: u32,
157    },
158    /// No action is required before this monotonic timestamp.
159    WaitUntil(u64),
160    /// The delivery is terminal.
161    Complete(DeliveryOutcome),
162}
163
164/// Result of recording an acknowledgement.
165#[derive(Debug, Clone, Copy, PartialEq, Eq)]
166pub enum AckResult {
167    /// The first valid acknowledgement completed the delivery.
168    Accepted,
169    /// Delivery was already acknowledged; no state changed.
170    Duplicate,
171}
172
173/// Stateful delivery coordinator for one envelope.
174#[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    /// Creates a ready delivery at the envelope's creation timestamp.
185    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    /// Returns the envelope.
197    pub const fn envelope(&self) -> &Envelope<T> {
198        &self.envelope
199    }
200
201    /// Returns the policy.
202    pub const fn policy(&self) -> DeliveryPolicy {
203        self.policy
204    }
205
206    /// Returns the current state.
207    pub const fn state(&self) -> DeliveryState {
208        self.state
209    }
210
211    /// Returns the number of send attempts already recorded.
212    pub const fn attempts(&self) -> u32 {
213        self.attempts
214    }
215
216    /// Advances protocol time and returns the next instruction.
217    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    /// Records that the caller performed the currently available send.
251    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    /// Records an acknowledgement, accepting duplicates idempotently.
281    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/// Invalid configuration, time, or protocol transition.
349#[derive(Debug, Clone, PartialEq, Eq)]
350pub enum ProtocolError {
351    /// The envelope identifier was blank.
352    EmptyMessageId,
353    /// The envelope time-to-live was zero.
354    ZeroTimeToLive,
355    /// The acknowledgement timeout was zero.
356    ZeroAcknowledgementTimeout,
357    /// The maximum attempt count was zero.
358    ZeroMaxAttempts,
359    /// Timestamp arithmetic overflowed.
360    TimeOverflow,
361    /// A timestamp was older than a previously observed timestamp.
362    TimeMovedBackwards {
363        /// Most recently observed timestamp.
364        previous_ms: u64,
365        /// Newly supplied timestamp.
366        supplied_ms: u64,
367    },
368    /// A send was recorded while acknowledgement was already pending.
369    SendAlreadyAwaitingAcknowledgement,
370    /// An acknowledgement arrived before any send was recorded.
371    UnexpectedAcknowledgement,
372    /// An operation was attempted after terminal completion.
373    DeliveryAlreadyTerminal,
374    /// A send was requested after all attempts were used.
375    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}