use crate::policy::ladder::Step;
use crate::status::{ApiClass, PageClass};
#[derive(Debug, Clone, PartialEq)]
#[non_exhaustive]
pub enum Trigger {
Api(ApiClass),
Page(PageClass),
EmptyContent,
Timeout,
Connect,
}
impl Trigger {
pub fn retry_only(&self) -> bool {
matches!(
self,
Trigger::Api(ApiClass::RateLimited { .. }) | Trigger::Api(ApiClass::Draining { .. })
)
}
pub fn is_api_plane(&self) -> bool {
matches!(self, Trigger::Api(_) | Trigger::Timeout | Trigger::Connect)
}
}
#[derive(Debug, Clone, PartialEq)]
#[non_exhaustive]
pub enum Decision {
Accept,
RetrySame {
max: u8,
},
Escalate,
EscalateTo(Step),
Fail,
}
#[derive(Debug, Clone, PartialEq)]
pub struct Rule {
pub when: Trigger,
pub then: Decision,
}
impl Rule {
pub fn new(when: Trigger, then: Decision) -> Rule {
Rule { when, then }
}
}
pub fn default_rules() -> Vec<Rule> {
vec![
Rule::new(Trigger::EmptyContent, Decision::Escalate),
Rule::new(Trigger::Page(PageClass::Ok), Decision::Accept),
Rule::new(Trigger::Page(PageClass::BadRequest), Decision::Fail),
Rule::new(Trigger::Page(PageClass::NeedsLogin), Decision::Fail),
Rule::new(Trigger::Page(PageClass::Blocked), Decision::Escalate),
Rule::new(Trigger::Page(PageClass::NotFound), Decision::Fail),
Rule::new(
Trigger::Page(PageClass::TargetRateLimited),
Decision::RetrySame { max: 1 },
),
Rule::new(
Trigger::Page(PageClass::ServerError),
Decision::RetrySame { max: 1 },
),
Rule::new(Trigger::Api(ApiClass::Ok), Decision::Accept),
Rule::new(Trigger::Api(ApiClass::NoContent), Decision::Accept),
Rule::new(Trigger::Api(ApiClass::BadRequest), Decision::Fail),
Rule::new(Trigger::Api(ApiClass::Unauthorized), Decision::Fail),
Rule::new(Trigger::Api(ApiClass::InsufficientCredits), Decision::Fail),
Rule::new(Trigger::Api(ApiClass::PayloadTooLarge), Decision::Fail),
Rule::new(
Trigger::Api(ApiClass::RateLimited { retry_after: None }),
Decision::RetrySame { max: 3 },
),
Rule::new(
Trigger::Api(ApiClass::ServerError),
Decision::RetrySame { max: 1 },
),
Rule::new(
Trigger::Api(ApiClass::Draining { retry_after: None }),
Decision::RetrySame { max: 3 },
),
Rule::new(Trigger::Timeout, Decision::RetrySame { max: 1 }),
Rule::new(Trigger::Connect, Decision::RetrySame { max: 1 }),
]
}
#[cfg(test)]
mod tests {
#![allow(
clippy::unwrap_used,
clippy::expect_used,
clippy::panic,
clippy::unreachable,
clippy::indexing_slicing,
clippy::string_slice
)]
use super::*;
fn position(rules: &[Rule], trigger: &Trigger) -> usize {
rules
.iter()
.position(|rule| &rule.when == trigger)
.unwrap_or_else(|| panic!("no rule for {trigger:?}"))
}
#[test]
fn a_blank_page_is_read_before_a_served_one() {
let rules = default_rules();
assert!(
position(&rules, &Trigger::EmptyContent)
< position(&rules, &Trigger::Page(PageClass::Ok)),
"a blank 2xx would be accepted instead of escalated"
);
}
#[test]
fn every_mapped_class_on_both_planes_has_a_rule() {
let rules = default_rules();
for class in [
PageClass::Ok,
PageClass::BadRequest,
PageClass::NeedsLogin,
PageClass::Blocked,
PageClass::NotFound,
PageClass::TargetRateLimited,
PageClass::ServerError,
] {
position(&rules, &Trigger::Page(class));
}
for class in [
ApiClass::Ok,
ApiClass::NoContent,
ApiClass::BadRequest,
ApiClass::Unauthorized,
ApiClass::InsufficientCredits,
ApiClass::PayloadTooLarge,
ApiClass::RateLimited { retry_after: None },
ApiClass::ServerError,
ApiClass::Draining { retry_after: None },
] {
position(&rules, &Trigger::Api(class));
}
position(&rules, &Trigger::Timeout);
position(&rules, &Trigger::Connect);
}
#[test]
fn running_out_of_credits_is_never_a_retry() {
let rules = default_rules();
let index = position(&rules, &Trigger::Api(ApiClass::InsufficientCredits));
assert_eq!(rules[index].then, Decision::Fail);
}
#[test]
fn a_missing_page_is_never_a_retry_and_never_an_escalation() {
let rules = default_rules();
let index = position(&rules, &Trigger::Page(PageClass::NotFound));
assert_eq!(rules[index].then, Decision::Fail);
}
#[test]
fn every_transient_api_status_has_a_retry_rule_the_caller_agrees_with() {
use crate::status::api::TRANSIENT;
use crate::status::ApiStatus;
let rules = default_rules();
for code in TRANSIENT {
let status = ApiStatus::new(code);
let index = position(&rules, &Trigger::Api(status.class()));
assert!(
matches!(rules[index].then, Decision::RetrySame { .. }),
"api {code} is transient but its rule does not retry"
);
let error = crate::Error::Api {
status,
message: None,
retry_after: None,
};
assert!(
error.is_retryable(),
"api {code} is retried but not retryable"
);
}
for code in 100..=599u16 {
let status = ApiStatus::new(code);
let retried = rules.iter().any(|rule| {
rule.when == Trigger::Api(status.class())
&& matches!(rule.then, Decision::RetrySame { .. })
});
let error = crate::Error::Api {
status,
message: None,
retry_after: None,
};
assert_eq!(error.is_retryable(), retried, "api {code}");
}
}
#[test]
fn only_the_accounts_own_limits_stop_instead_of_climbing() {
assert!(Trigger::Api(ApiClass::RateLimited { retry_after: None }).retry_only());
assert!(Trigger::Api(ApiClass::Draining { retry_after: None }).retry_only());
assert!(!Trigger::Api(ApiClass::ServerError).retry_only());
assert!(!Trigger::Page(PageClass::TargetRateLimited).retry_only());
assert!(!Trigger::Timeout.retry_only());
assert!(!Trigger::Connect.retry_only());
}
#[test]
fn the_planes_are_labelled() {
assert!(Trigger::Api(ApiClass::Ok).is_api_plane());
assert!(Trigger::Timeout.is_api_plane());
assert!(Trigger::Connect.is_api_plane());
assert!(!Trigger::Page(PageClass::Ok).is_api_plane());
assert!(!Trigger::EmptyContent.is_api_plane());
}
}