use crate::platform::{Duration, Instant};
pub const PASE_ESTABLISHMENT_TIMEOUT: Duration = Duration::from_secs(60);
pub const MAX_FAILED_ATTEMPTS: u8 = 20;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Admit {
Admitted,
Busy,
NotCommissionable,
AttemptsExhausted,
}
impl Admit {
#[must_use]
pub const fn is_admitted(self) -> bool {
matches!(self, Self::Admitted)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub struct Failure {
pub attempts: u8,
pub exit_commissioning_mode: bool,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Channel {
Idle,
Establishing {
deadline: Instant,
},
Established,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct PaseAdmission {
channel: Channel,
failures: u8,
}
impl Default for PaseAdmission {
fn default() -> Self {
Self::new()
}
}
impl PaseAdmission {
#[must_use]
pub const fn new() -> Self {
Self {
channel: Channel::Idle,
failures: 0,
}
}
pub fn admit(&mut self, commissionable: bool, now: Instant) -> Admit {
self.expire(now);
if self.failures >= MAX_FAILED_ATTEMPTS {
return Admit::AttemptsExhausted;
}
if !commissionable {
return Admit::NotCommissionable;
}
match self.channel {
Channel::Establishing { .. } | Channel::Established => Admit::Busy,
Channel::Idle => {
self.channel = Channel::Establishing {
deadline: now.saturating_add(PASE_ESTABLISHMENT_TIMEOUT),
};
Admit::Admitted
}
}
}
pub const fn established(&mut self) {
self.channel = Channel::Established;
self.failures = 0;
}
pub const fn failed(&mut self) -> Failure {
self.channel = Channel::Idle;
self.failures = self.failures.saturating_add(1);
Failure {
attempts: self.failures,
exit_commissioning_mode: self.failures >= MAX_FAILED_ATTEMPTS,
}
}
pub const fn closed(&mut self) {
self.channel = Channel::Idle;
}
pub const fn reset(&mut self) {
self.channel = Channel::Idle;
self.failures = 0;
}
pub const fn poll(&mut self, now: Instant) -> Option<Failure> {
if self.expire(now) {
Some(Failure {
attempts: self.failures,
exit_commissioning_mode: self.failures >= MAX_FAILED_ATTEMPTS,
})
} else {
None
}
}
const fn expire(&mut self, now: Instant) -> bool {
if let Channel::Establishing { deadline } = self.channel
&& now.as_micros() > deadline.as_micros()
{
self.channel = Channel::Idle;
self.failures = self.failures.saturating_add(1);
return true;
}
false
}
#[must_use]
pub const fn deadline(&self) -> Option<Instant> {
match self.channel {
Channel::Establishing { deadline } => Some(deadline),
Channel::Idle | Channel::Established => None,
}
}
#[must_use]
pub const fn failures(&self) -> u8 {
self.failures
}
#[must_use]
pub const fn is_exhausted(&self) -> bool {
self.failures >= MAX_FAILED_ATTEMPTS
}
#[must_use]
pub const fn is_established(&self) -> bool {
matches!(self.channel, Channel::Established)
}
#[must_use]
pub const fn is_establishing(&self) -> bool {
matches!(self.channel, Channel::Establishing { .. })
}
}
#[cfg(test)]
#[allow(clippy::arithmetic_side_effects, clippy::indexing_slicing)]
mod tests {
use super::*;
fn at(secs: u64) -> Instant {
Instant::ZERO.saturating_add(Duration::from_secs(secs))
}
#[test]
fn a_factory_new_node_admits_the_first_request() {
let mut gate = PaseAdmission::new();
assert_eq!(gate.admit(true, at(0)), Admit::Admitted);
assert!(gate.is_establishing());
}
#[test]
fn a_second_request_while_establishing_is_refused() {
let mut gate = PaseAdmission::new();
assert_eq!(gate.admit(true, at(0)), Admit::Admitted);
assert_eq!(gate.admit(true, at(1)), Admit::Busy);
assert_eq!(gate.admit(true, at(59)), Admit::Busy);
}
#[test]
fn a_request_while_a_session_is_established_is_refused() {
let mut gate = PaseAdmission::new();
assert!(gate.admit(true, at(0)).is_admitted());
gate.established();
assert_eq!(gate.admit(true, at(1)), Admit::Busy);
gate.closed();
assert_eq!(gate.admit(true, at(2)), Admit::Admitted);
}
#[test]
fn a_failed_establishment_frees_the_channel() {
let mut gate = PaseAdmission::new();
assert!(gate.admit(true, at(0)).is_admitted());
let failure = gate.failed();
assert_eq!(failure.attempts, 1);
assert!(!failure.exit_commissioning_mode);
assert_eq!(gate.admit(true, at(1)), Admit::Admitted);
}
#[test]
fn an_establishment_expires_after_sixty_seconds() {
let mut gate = PaseAdmission::new();
assert!(gate.admit(true, at(0)).is_admitted());
assert_eq!(
gate.poll(at(60)),
None,
"exactly on the deadline is not late"
);
let Some(failure) = gate.poll(at(61)) else {
panic!("the deadline passed")
};
assert_eq!(failure.attempts, 1);
assert!(!gate.is_establishing());
assert_eq!(gate.admit(true, at(62)), Admit::Admitted);
}
#[test]
fn an_expired_establishment_does_not_block_the_next_request() {
let mut gate = PaseAdmission::new();
assert!(gate.admit(true, at(0)).is_admitted());
assert_eq!(gate.admit(true, at(61)), Admit::Admitted);
assert_eq!(gate.failures(), 1, "the abandoned attempt still counted");
}
#[test]
fn twenty_failures_end_commissioning_mode() {
let mut gate = PaseAdmission::new();
for n in 1..MAX_FAILED_ATTEMPTS {
assert!(gate.admit(true, at(0)).is_admitted(), "attempt {n}");
let failure = gate.failed();
assert!(!failure.exit_commissioning_mode, "attempt {n}");
}
assert!(gate.admit(true, at(0)).is_admitted());
let last = gate.failed();
assert_eq!(last.attempts, MAX_FAILED_ATTEMPTS);
assert!(last.exit_commissioning_mode);
assert!(gate.is_exhausted());
assert_eq!(gate.admit(true, at(0)), Admit::AttemptsExhausted);
}
#[test]
fn a_new_window_readmits_an_exhausted_node() {
let mut gate = PaseAdmission::new();
for _ in 0..MAX_FAILED_ATTEMPTS {
let _ = gate.admit(true, at(0));
let _ = gate.failed();
}
assert_eq!(gate.admit(true, at(0)), Admit::AttemptsExhausted);
gate.reset();
assert_eq!(gate.admit(true, at(0)), Admit::Admitted);
}
#[test]
fn success_clears_the_failure_count() {
let mut gate = PaseAdmission::new();
for _ in 0..5 {
let _ = gate.admit(true, at(0));
let _ = gate.failed();
}
assert_eq!(gate.failures(), 5);
assert!(gate.admit(true, at(0)).is_admitted());
gate.established();
assert_eq!(gate.failures(), 0);
}
#[test]
fn closing_an_established_session_is_not_a_failure() {
let mut gate = PaseAdmission::new();
assert!(gate.admit(true, at(0)).is_admitted());
gate.established();
gate.closed();
assert_eq!(gate.failures(), 0);
}
#[test]
fn a_commissioned_node_with_no_window_is_not_commissionable() {
let mut gate = PaseAdmission::new();
assert_eq!(gate.admit(false, at(0)), Admit::NotCommissionable);
assert!(!gate.is_establishing(), "a refusal starts no clock");
}
#[test]
fn exhaustion_is_reported_before_commissionability() {
let mut gate = PaseAdmission::new();
for _ in 0..MAX_FAILED_ATTEMPTS {
let _ = gate.admit(true, at(0));
let _ = gate.failed();
}
assert_eq!(gate.admit(false, at(0)), Admit::AttemptsExhausted);
}
#[test]
fn the_deadline_is_only_live_while_establishing() {
let mut gate = PaseAdmission::new();
assert_eq!(gate.deadline(), None);
assert!(gate.admit(true, at(0)).is_admitted());
assert_eq!(gate.deadline(), Some(at(60)));
gate.established();
assert_eq!(
gate.deadline(),
None,
"an established session has no deadline"
);
}
}