use std::time::Duration;
use http::{HeaderName, HeaderValue};
use runlimit_core::{Decision, DecisionView, RateLimitPolicy};
use thiserror::Error;
pub const MAX_STRUCTURED_FIELD_INTEGER: u64 = 999_999_999_999_999;
pub const MAX_POLICY_NAME_LENGTH: usize = 128;
pub type HeaderField = (HeaderName, HeaderValue);
pub fn quota_policy<P: RateLimitPolicy + ?Sized>(
name: &str,
policy: &P,
) -> Result<HeaderField, EncodingError> {
let name = encode_policy_name(name)?;
let quota = structured_integer(policy.quota())?;
let period = policy.quota_period();
if period.is_zero() {
return Err(EncodingError::ZeroQuotaPeriod);
}
if period.subsec_nanos() != 0 {
return Err(EncodingError::QuotaPeriodNotWholeSeconds { actual: period });
}
let period = structured_integer(period.as_secs())?;
let value = header_value(format!("{name};q={quota};w={period}"))?;
Ok((HeaderName::from_static("ratelimit-policy"), value))
}
pub fn service_limit(name: &str, decision: &Decision) -> Result<HeaderField, EncodingError> {
let name = encode_policy_name(name)?;
let (available, effective_window) = match decision.view() {
DecisionView::Allowed {
available,
replenishes_after,
..
} => (available, replenishes_after),
DecisionView::Denied { denial } => match denial.quota() {
Some(denial) => (0, denial.retry_after()),
None => return Err(EncodingError::UnsupportedDecision),
},
DecisionView::ShadowDenied { denial } => (0, denial.retry_after()),
};
let available = structured_integer(available)?;
let effective_window = structured_integer(ceil_seconds(effective_window))?;
let value = header_value(format!("{name};r={available};t={effective_window}"))?;
Ok((HeaderName::from_static("ratelimit"), value))
}
fn encode_policy_name(name: &str) -> Result<String, EncodingError> {
if name.is_empty() {
return Err(EncodingError::EmptyPolicyName);
}
if name.len() > MAX_POLICY_NAME_LENGTH {
return Err(EncodingError::PolicyNameTooLong {
actual: name.len(),
maximum: MAX_POLICY_NAME_LENGTH,
});
}
let mut encoded = String::with_capacity(name.len() + 2);
encoded.push('"');
for (index, character) in name.char_indices() {
if !matches!(character, '\u{20}'..='\u{7e}') {
return Err(EncodingError::InvalidPolicyNameCharacter { index, character });
}
if matches!(character, '"' | '\\') {
encoded.push('\\');
}
encoded.push(character);
}
encoded.push('"');
Ok(encoded)
}
fn structured_integer(value: u64) -> Result<u64, EncodingError> {
if value > MAX_STRUCTURED_FIELD_INTEGER {
return Err(EncodingError::StructuredFieldIntegerTooLarge {
actual: value,
maximum: MAX_STRUCTURED_FIELD_INTEGER,
});
}
Ok(value)
}
fn ceil_seconds(duration: Duration) -> u64 {
duration
.as_secs()
.saturating_add(u64::from(duration.subsec_nanos() != 0))
}
fn header_value(value: String) -> Result<HeaderValue, EncodingError> {
HeaderValue::try_from(value).map_err(|_| EncodingError::InvalidHeaderValue)
}
#[derive(Clone, Debug, Error, Eq, PartialEq)]
#[non_exhaustive]
pub enum EncodingError {
#[error("RateLimit policy name must not be empty")]
EmptyPolicyName,
#[error("RateLimit policy name is {actual} bytes; the maximum is {maximum}")]
PolicyNameTooLong {
actual: usize,
maximum: usize,
},
#[error(
"RateLimit policy name contains invalid character {character:?} at byte index {index}; \
use visible ASCII"
)]
InvalidPolicyNameCharacter {
index: usize,
character: char,
},
#[error("Structured Field integer {actual} exceeds maximum {maximum}")]
StructuredFieldIntegerTooLarge {
actual: u64,
maximum: u64,
},
#[error("RateLimit-Policy quota period must be greater than zero")]
ZeroQuotaPeriod,
#[error("RateLimit-Policy quota period {actual:?} is not an exact whole number of seconds")]
QuotaPeriodNotWholeSeconds {
actual: Duration,
},
#[error("the decision cannot be represented as a RateLimit quota service limit")]
UnsupportedDecision,
#[error("encoded RateLimit metadata is not a valid HTTP header value")]
InvalidHeaderValue,
}
#[cfg(test)]
mod tests {
use std::time::Duration;
use runlimit_core::{
Decision, Denial, FixedWindowPolicy, GcraPolicy, PolicyFingerprint, PolicyId, QuotaDenial,
QuotaMode, RateLimitPolicy, ScopeId,
};
use super::{
EncodingError, MAX_POLICY_NAME_LENGTH, MAX_STRUCTURED_FIELD_INTEGER, quota_policy,
service_limit,
};
fn fixed_policy(limit: u64, window: Duration) -> FixedWindowPolicy {
FixedWindowPolicy::new(
PolicyId::new("api.search").unwrap(),
ScopeId::new("client").unwrap(),
limit,
window,
)
.unwrap()
}
#[derive(Debug)]
struct PeriodOverride {
policy: FixedWindowPolicy,
period: Duration,
}
impl RateLimitPolicy for PeriodOverride {
fn id(&self) -> &PolicyId {
self.policy.id()
}
fn scope(&self) -> &ScopeId {
self.policy.scope()
}
fn quota(&self) -> u64 {
self.policy.limit()
}
fn quota_period(&self) -> Duration {
self.period
}
fn capacity(&self) -> u64 {
self.policy.limit()
}
fn fingerprint(&self) -> PolicyFingerprint {
self.policy.fingerprint()
}
fn quota_mode(&self) -> QuotaMode {
self.policy.quota_mode()
}
}
#[test]
fn encodes_exact_draft_11_golden_fields() {
let policy = fixed_policy(100, Duration::from_secs(60));
let policy_field = quota_policy("search", &policy).unwrap();
let service_field = service_limit(
"search",
&Decision::allowed(100, 49, Duration::from_secs(37)),
)
.unwrap();
assert_eq!(policy_field.0.as_str(), "ratelimit-policy");
assert_eq!(policy_field.1, "\"search\";q=100;w=60");
assert_eq!(service_field.0.as_str(), "ratelimit");
assert_eq!(service_field.1, "\"search\";r=49;t=37");
}
#[test]
fn uses_algorithm_neutral_gcra_policy_metadata() {
let policy = GcraPolicy::new(
PolicyId::new("api.upload").unwrap(),
ScopeId::new("account").unwrap(),
10,
Duration::from_secs(60),
4,
)
.unwrap();
assert_eq!(
quota_policy("upload", &policy).unwrap().1,
"\"upload\";q=10;w=60"
);
}
#[test]
fn quota_and_shadow_denials_are_would_deny_service_values() {
let denial = QuotaDenial::try_new(10, Duration::from_millis(1_001)).unwrap();
assert_eq!(
service_limit("default", &Decision::denied(denial))
.unwrap()
.1,
"\"default\";r=0;t=2"
);
assert_eq!(
service_limit("default", &Decision::shadow_denied(denial))
.unwrap()
.1,
"\"default\";r=0;t=2"
);
}
#[test]
fn rounds_allowed_effective_windows_up_to_whole_seconds() {
let decision = Decision::allowed(10, 9, Duration::from_nanos(1));
assert_eq!(
service_limit("default", &decision).unwrap().1,
"\"default\";r=9;t=1"
);
}
#[test]
fn escapes_structured_field_strings_without_header_injection() {
let policy = fixed_policy(5, Duration::from_secs(1));
assert_eq!(
quota_policy("quoted \"name\" \\ path", &policy).unwrap().1,
"\"quoted \\\"name\\\" \\\\ path\";q=5;w=1"
);
assert_eq!(
quota_policy("bad\r\ninjected: value", &policy),
Err(EncodingError::InvalidPolicyNameCharacter {
index: 3,
character: '\r',
})
);
assert_eq!(
quota_policy("café", &policy),
Err(EncodingError::InvalidPolicyNameCharacter {
index: 3,
character: 'é',
})
);
}
#[test]
fn rejects_empty_and_oversized_policy_names() {
let policy = fixed_policy(5, Duration::from_secs(1));
assert_eq!(
quota_policy("", &policy),
Err(EncodingError::EmptyPolicyName)
);
assert_eq!(
quota_policy(&"a".repeat(MAX_POLICY_NAME_LENGTH + 1), &policy),
Err(EncodingError::PolicyNameTooLong {
actual: MAX_POLICY_NAME_LENGTH + 1,
maximum: MAX_POLICY_NAME_LENGTH,
})
);
}
#[test]
fn accepts_the_structured_field_integer_maximum_and_rejects_larger_values() {
let maximum = fixed_policy(MAX_STRUCTURED_FIELD_INTEGER, Duration::from_secs(1));
let too_large = fixed_policy(MAX_STRUCTURED_FIELD_INTEGER + 1, Duration::from_secs(1));
assert_eq!(
quota_policy("maximum", &maximum).unwrap().1,
"\"maximum\";q=999999999999999;w=1"
);
assert_eq!(
quota_policy("too-large", &too_large),
Err(EncodingError::StructuredFieldIntegerTooLarge {
actual: MAX_STRUCTURED_FIELD_INTEGER + 1,
maximum: MAX_STRUCTURED_FIELD_INTEGER,
})
);
assert_eq!(
service_limit(
"too-large",
&Decision::allowed(
MAX_STRUCTURED_FIELD_INTEGER + 1,
MAX_STRUCTURED_FIELD_INTEGER + 1,
Duration::from_secs(1),
),
),
Err(EncodingError::StructuredFieldIntegerTooLarge {
actual: MAX_STRUCTURED_FIELD_INTEGER + 1,
maximum: MAX_STRUCTURED_FIELD_INTEGER,
})
);
}
#[test]
fn rejects_non_whole_second_policy_periods() {
let policy = fixed_policy(5, Duration::from_millis(1_500));
assert_eq!(
quota_policy("fractional", &policy),
Err(EncodingError::QuotaPeriodNotWholeSeconds {
actual: Duration::from_millis(1_500),
})
);
}
#[test]
fn rejects_zero_policy_periods_from_custom_policies() {
let policy = PeriodOverride {
policy: fixed_policy(5, Duration::from_secs(1)),
period: Duration::ZERO,
};
assert_eq!(
quota_policy("zero", &policy),
Err(EncodingError::ZeroQuotaPeriod)
);
}
#[test]
fn rejects_capacity_denials_as_quota_service_limits() {
let decision = Decision::denied(Denial::storage_capacity(Some(Duration::from_secs(1))));
assert_eq!(
service_limit("default", &decision),
Err(EncodingError::UnsupportedDecision)
);
}
#[test]
fn rejects_effective_windows_above_the_structured_field_integer_maximum() {
let decision =
Decision::allowed(1, 0, Duration::from_secs(MAX_STRUCTURED_FIELD_INTEGER + 1));
assert_eq!(
service_limit("default", &decision),
Err(EncodingError::StructuredFieldIntegerTooLarge {
actual: MAX_STRUCTURED_FIELD_INTEGER + 1,
maximum: MAX_STRUCTURED_FIELD_INTEGER,
})
);
}
}