#![forbid(unsafe_code)]
#![warn(missing_docs)]
use std::error::Error;
use std::fmt;
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Envelope<T> {
id: String,
payload: T,
created_at_ms: u64,
expires_at_ms: u64,
}
impl<T> Envelope<T> {
pub fn new(
id: impl Into<String>,
payload: T,
created_at_ms: u64,
ttl_ms: u64,
) -> Result<Self, ProtocolError> {
let id = id.into();
if id.trim().is_empty() {
return Err(ProtocolError::EmptyMessageId);
}
if ttl_ms == 0 {
return Err(ProtocolError::ZeroTimeToLive);
}
let expires_at_ms = created_at_ms
.checked_add(ttl_ms)
.ok_or(ProtocolError::TimeOverflow)?;
Ok(Self {
id,
payload,
created_at_ms,
expires_at_ms,
})
}
pub fn id(&self) -> &str {
&self.id
}
pub const fn payload(&self) -> &T {
&self.payload
}
pub const fn created_at_ms(&self) -> u64 {
self.created_at_ms
}
pub const fn expires_at_ms(&self) -> u64 {
self.expires_at_ms
}
pub fn into_payload(self) -> T {
self.payload
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct DeliveryPolicy {
acknowledgement_timeout_ms: u64,
max_attempts: u32,
}
impl DeliveryPolicy {
pub fn new(acknowledgement_timeout_ms: u64, max_attempts: u32) -> Result<Self, ProtocolError> {
if acknowledgement_timeout_ms == 0 {
return Err(ProtocolError::ZeroAcknowledgementTimeout);
}
if max_attempts == 0 {
return Err(ProtocolError::ZeroMaxAttempts);
}
Ok(Self {
acknowledgement_timeout_ms,
max_attempts,
})
}
pub const fn acknowledgement_timeout_ms(self) -> u64 {
self.acknowledgement_timeout_ms
}
pub const fn max_attempts(self) -> u32 {
self.max_attempts
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DeliveryState {
Ready,
AwaitingAcknowledgement {
sent_at_ms: u64,
retry_at_ms: u64,
},
Delivered {
acknowledged_at_ms: u64,
},
Expired {
observed_at_ms: u64,
},
Exhausted {
observed_at_ms: u64,
},
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DeliveryOutcome {
Delivered,
Expired,
Exhausted,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NextAction {
SendNow {
attempt: u32,
},
WaitUntil(u64),
Complete(DeliveryOutcome),
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AckResult {
Accepted,
Duplicate,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Delivery<T> {
envelope: Envelope<T>,
policy: DeliveryPolicy,
state: DeliveryState,
attempts: u32,
last_observed_ms: u64,
}
impl<T> Delivery<T> {
pub const fn new(envelope: Envelope<T>, policy: DeliveryPolicy) -> Self {
let last_observed_ms = envelope.created_at_ms;
Self {
envelope,
policy,
state: DeliveryState::Ready,
attempts: 0,
last_observed_ms,
}
}
pub const fn envelope(&self) -> &Envelope<T> {
&self.envelope
}
pub const fn policy(&self) -> DeliveryPolicy {
self.policy
}
pub const fn state(&self) -> DeliveryState {
self.state
}
pub const fn attempts(&self) -> u32 {
self.attempts
}
pub fn poll(&mut self, now_ms: u64) -> Result<NextAction, ProtocolError> {
self.observe(now_ms)?;
if let Some(outcome) = terminal_outcome(self.state) {
return Ok(NextAction::Complete(outcome));
}
if self.expire_if_due(now_ms) {
return Ok(NextAction::Complete(DeliveryOutcome::Expired));
}
match self.state {
DeliveryState::Ready => self.ready_action(now_ms),
DeliveryState::AwaitingAcknowledgement { retry_at_ms, .. } => {
if now_ms < retry_at_ms {
Ok(NextAction::WaitUntil(
retry_at_ms.min(self.envelope.expires_at_ms),
))
} else if self.attempts < self.policy.max_attempts {
self.state = DeliveryState::Ready;
self.ready_action(now_ms)
} else {
self.state = DeliveryState::Exhausted {
observed_at_ms: now_ms,
};
Ok(NextAction::Complete(DeliveryOutcome::Exhausted))
}
}
DeliveryState::Delivered { .. }
| DeliveryState::Expired { .. }
| DeliveryState::Exhausted { .. } => unreachable!("terminal states handled above"),
}
}
pub fn record_sent(&mut self, now_ms: u64) -> Result<(), ProtocolError> {
self.observe(now_ms)?;
if terminal_outcome(self.state).is_some() {
return Err(ProtocolError::DeliveryAlreadyTerminal);
}
if self.expire_if_due(now_ms) {
return Err(ProtocolError::DeliveryAlreadyTerminal);
}
if self.state != DeliveryState::Ready {
return Err(ProtocolError::SendAlreadyAwaitingAcknowledgement);
}
if self.attempts >= self.policy.max_attempts {
self.state = DeliveryState::Exhausted {
observed_at_ms: now_ms,
};
return Err(ProtocolError::AttemptsExhausted);
}
let retry_at_ms = now_ms
.checked_add(self.policy.acknowledgement_timeout_ms)
.ok_or(ProtocolError::TimeOverflow)?;
self.attempts += 1;
self.state = DeliveryState::AwaitingAcknowledgement {
sent_at_ms: now_ms,
retry_at_ms,
};
Ok(())
}
pub fn acknowledge(&mut self, now_ms: u64) -> Result<AckResult, ProtocolError> {
self.observe(now_ms)?;
if matches!(self.state, DeliveryState::Delivered { .. }) {
return Ok(AckResult::Duplicate);
}
if terminal_outcome(self.state).is_some() {
return Err(ProtocolError::DeliveryAlreadyTerminal);
}
if self.expire_if_due(now_ms) {
return Err(ProtocolError::DeliveryAlreadyTerminal);
}
if matches!(self.state, DeliveryState::AwaitingAcknowledgement { .. }) {
self.state = DeliveryState::Delivered {
acknowledged_at_ms: now_ms,
};
Ok(AckResult::Accepted)
} else {
Err(ProtocolError::UnexpectedAcknowledgement)
}
}
fn ready_action(&mut self, now_ms: u64) -> Result<NextAction, ProtocolError> {
if self.attempts < self.policy.max_attempts {
Ok(NextAction::SendNow {
attempt: self.attempts + 1,
})
} else {
self.state = DeliveryState::Exhausted {
observed_at_ms: now_ms,
};
Ok(NextAction::Complete(DeliveryOutcome::Exhausted))
}
}
fn observe(&mut self, now_ms: u64) -> Result<(), ProtocolError> {
if now_ms < self.last_observed_ms {
return Err(ProtocolError::TimeMovedBackwards {
previous_ms: self.last_observed_ms,
supplied_ms: now_ms,
});
}
self.last_observed_ms = now_ms;
Ok(())
}
fn expire_if_due(&mut self, now_ms: u64) -> bool {
if now_ms >= self.envelope.expires_at_ms {
self.state = DeliveryState::Expired {
observed_at_ms: now_ms,
};
true
} else {
false
}
}
}
fn terminal_outcome(state: DeliveryState) -> Option<DeliveryOutcome> {
match state {
DeliveryState::Delivered { .. } => Some(DeliveryOutcome::Delivered),
DeliveryState::Expired { .. } => Some(DeliveryOutcome::Expired),
DeliveryState::Exhausted { .. } => Some(DeliveryOutcome::Exhausted),
DeliveryState::Ready | DeliveryState::AwaitingAcknowledgement { .. } => None,
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ProtocolError {
EmptyMessageId,
ZeroTimeToLive,
ZeroAcknowledgementTimeout,
ZeroMaxAttempts,
TimeOverflow,
TimeMovedBackwards {
previous_ms: u64,
supplied_ms: u64,
},
SendAlreadyAwaitingAcknowledgement,
UnexpectedAcknowledgement,
DeliveryAlreadyTerminal,
AttemptsExhausted,
}
impl fmt::Display for ProtocolError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::EmptyMessageId => formatter.write_str("message id must not be blank"),
Self::ZeroTimeToLive => formatter.write_str("time-to-live must be greater than zero"),
Self::ZeroAcknowledgementTimeout => {
formatter.write_str("acknowledgement timeout must be greater than zero")
}
Self::ZeroMaxAttempts => {
formatter.write_str("maximum attempts must be greater than zero")
}
Self::TimeOverflow => formatter.write_str("timestamp arithmetic overflowed"),
Self::TimeMovedBackwards {
previous_ms,
supplied_ms,
} => write!(
formatter,
"time moved backwards from {previous_ms} to {supplied_ms}"
),
Self::SendAlreadyAwaitingAcknowledgement => {
formatter.write_str("a send is already awaiting acknowledgement")
}
Self::UnexpectedAcknowledgement => {
formatter.write_str("acknowledgement arrived before a send")
}
Self::DeliveryAlreadyTerminal => formatter.write_str("delivery is already terminal"),
Self::AttemptsExhausted => formatter.write_str("all send attempts are exhausted"),
}
}
}
impl Error for ProtocolError {}
#[cfg(test)]
mod tests {
use super::*;
fn delivery(ttl: u64, timeout: u64, attempts: u32) -> Delivery<&'static str> {
Delivery::new(
Envelope::new("message-1", "payload", 1_000, ttl).unwrap(),
DeliveryPolicy::new(timeout, attempts).unwrap(),
)
}
#[test]
fn ready_send_and_wait_are_explicit() {
let mut delivery = delivery(10_000, 500, 3);
assert_eq!(
delivery.poll(1_000).unwrap(),
NextAction::SendNow { attempt: 1 }
);
delivery.record_sent(1_000).unwrap();
assert_eq!(delivery.attempts(), 1);
assert_eq!(delivery.poll(1_200).unwrap(), NextAction::WaitUntil(1_500));
}
#[test]
fn timeout_enables_next_numbered_attempt() {
let mut delivery = delivery(10_000, 500, 3);
delivery.record_sent(1_000).unwrap();
assert_eq!(
delivery.poll(1_500).unwrap(),
NextAction::SendNow { attempt: 2 }
);
delivery.record_sent(1_500).unwrap();
assert_eq!(delivery.attempts(), 2);
}
#[test]
fn attempt_limit_terminates_delivery() {
let mut delivery = delivery(10_000, 100, 2);
delivery.record_sent(1_000).unwrap();
assert_eq!(
delivery.poll(1_100).unwrap(),
NextAction::SendNow { attempt: 2 }
);
delivery.record_sent(1_100).unwrap();
assert_eq!(
delivery.poll(1_200).unwrap(),
NextAction::Complete(DeliveryOutcome::Exhausted)
);
}
#[test]
fn expiry_has_priority_over_retry() {
let mut delivery = delivery(200, 500, 3);
delivery.record_sent(1_000).unwrap();
assert_eq!(
delivery.poll(1_200).unwrap(),
NextAction::Complete(DeliveryOutcome::Expired)
);
}
#[test]
fn duplicate_acknowledgement_is_idempotent() {
let mut delivery = delivery(10_000, 500, 3);
delivery.record_sent(1_000).unwrap();
assert_eq!(delivery.acknowledge(1_100).unwrap(), AckResult::Accepted);
assert_eq!(delivery.acknowledge(1_200).unwrap(), AckResult::Duplicate);
assert_eq!(
delivery.poll(20_000).unwrap(),
NextAction::Complete(DeliveryOutcome::Delivered)
);
}
#[test]
fn late_ack_before_envelope_expiry_is_accepted() {
let mut delivery = delivery(10_000, 100, 3);
delivery.record_sent(1_000).unwrap();
assert_eq!(delivery.acknowledge(1_500).unwrap(), AckResult::Accepted);
}
#[test]
fn invalid_transitions_are_rejected() {
let mut delivery = delivery(10_000, 500, 3);
assert_eq!(
delivery.acknowledge(1_000),
Err(ProtocolError::UnexpectedAcknowledgement)
);
delivery.record_sent(1_000).unwrap();
assert_eq!(
delivery.record_sent(1_001),
Err(ProtocolError::SendAlreadyAwaitingAcknowledgement)
);
}
#[test]
fn time_cannot_move_backwards() {
let mut delivery = delivery(10_000, 500, 3);
delivery.poll(1_100).unwrap();
assert_eq!(
delivery.poll(1_099),
Err(ProtocolError::TimeMovedBackwards {
previous_ms: 1_100,
supplied_ms: 1_099,
})
);
}
#[test]
fn invalid_configuration_is_rejected() {
assert_eq!(
Envelope::new(" ", (), 0, 1),
Err(ProtocolError::EmptyMessageId)
);
assert_eq!(
Envelope::new("id", (), 0, 0),
Err(ProtocolError::ZeroTimeToLive)
);
assert_eq!(
DeliveryPolicy::new(0, 1),
Err(ProtocolError::ZeroAcknowledgementTimeout)
);
assert_eq!(
DeliveryPolicy::new(1, 0),
Err(ProtocolError::ZeroMaxAttempts)
);
}
}