1use crate::{Request, Response};
4use std::fmt;
5
6#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
7pub struct ApiVersion {
8 pub major: u16,
9 pub minor: u16,
10}
11
12impl ApiVersion {
13 pub const fn new(major: u16, minor: u16) -> Self {
14 Self { major, minor }
15 }
16
17 pub fn parse(value: &str) -> Result<Self, VersionError> {
18 let value = value.trim().strip_prefix('v').unwrap_or(value.trim());
19 let mut parts = value.split('.');
20 let major = parts
21 .next()
22 .and_then(|value| value.parse().ok())
23 .ok_or(VersionError::Invalid)?;
24 let minor = parts
25 .next()
26 .map(|value| value.parse().ok())
27 .unwrap_or(Some(0))
28 .ok_or(VersionError::Invalid)?;
29 if parts.next().is_some() {
30 return Err(VersionError::Invalid);
31 }
32 Ok(Self::new(major, minor))
33 }
34}
35
36impl fmt::Display for ApiVersion {
37 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
38 write!(formatter, "v{}.{}", self.major, self.minor)
39 }
40}
41
42#[derive(Debug, Clone, PartialEq, Eq)]
43pub struct VersionDecision {
44 pub selected: ApiVersion,
45 pub deprecated: bool,
46 pub sunset: Option<String>,
47}
48
49impl VersionDecision {
50 pub fn apply_headers(&self, response: Response) -> Response {
51 let response = response.header("API-Version", &self.selected.to_string());
52 if self.deprecated {
53 let response = response.header("Deprecation", "true");
54 if let Some(sunset) = &self.sunset {
55 return response.header("Sunset", sunset);
56 }
57 response
58 } else {
59 response
60 }
61 }
62}
63
64#[derive(Debug, Clone, PartialEq, Eq)]
65pub enum VersionError {
66 Missing,
67 Invalid,
68 Unsupported,
69}
70
71pub struct VersionNegotiator {
72 header_name: String,
73 supported: Vec<ApiVersion>,
74 default: Option<ApiVersion>,
75 deprecated: Vec<(ApiVersion, Option<String>)>,
76}
77
78impl VersionNegotiator {
79 pub fn new(supported: impl IntoIterator<Item = ApiVersion>) -> Self {
80 Self {
81 header_name: "Accept-Version".to_string(),
82 supported: supported.into_iter().collect(),
83 default: None,
84 deprecated: Vec::new(),
85 }
86 }
87
88 pub fn header_name(mut self, name: impl Into<String>) -> Self {
89 self.header_name = name.into();
90 self
91 }
92 pub fn default(mut self, version: ApiVersion) -> Self {
93 self.default = Some(version);
94 self
95 }
96 pub fn deprecated(mut self, version: ApiVersion, sunset: Option<String>) -> Self {
97 self.deprecated.push((version, sunset));
98 self
99 }
100
101 pub fn negotiate(&self, request: &Request) -> Result<VersionDecision, VersionError> {
102 let requested = request
103 .header(&self.header_name)
104 .map(ApiVersion::parse)
105 .transpose()?;
106 let selected = requested.or(self.default).ok_or(VersionError::Missing)?;
107 if !self.supported.contains(&selected) {
108 return Err(VersionError::Unsupported);
109 }
110 let sunset = self
111 .deprecated
112 .iter()
113 .find(|(version, _)| *version == selected)
114 .and_then(|(_, sunset)| sunset.clone());
115 Ok(VersionDecision {
116 selected,
117 deprecated: sunset.is_some()
118 || self
119 .deprecated
120 .iter()
121 .any(|(version, _)| *version == selected),
122 sunset,
123 })
124 }
125}
126
127#[cfg(test)]
128mod tests {
129 use super::*;
130 use hyper::{Body, Method, Request as HyperRequest};
131
132 async fn request(version: Option<&str>) -> Request {
133 let mut builder = HyperRequest::builder().method(Method::GET).uri("/");
134 if let Some(version) = version {
135 builder = builder.header("Accept-Version", version);
136 }
137 Request::from_hyper(builder.body(Body::empty()).unwrap())
138 .await
139 .unwrap()
140 }
141
142 #[test]
143 fn parses_common_version_forms() {
144 assert_eq!(ApiVersion::parse("v1").unwrap(), ApiVersion::new(1, 0));
145 assert_eq!(ApiVersion::parse("1.2").unwrap(), ApiVersion::new(1, 2));
146 assert!(matches!(
147 ApiVersion::parse("v1.2.3"),
148 Err(VersionError::Invalid)
149 ));
150 }
151
152 #[tokio::test]
153 async fn negotiates_default_and_deprecated_versions() {
154 let negotiator = VersionNegotiator::new([ApiVersion::new(1, 0), ApiVersion::new(2, 0)])
155 .default(ApiVersion::new(2, 0))
156 .deprecated(ApiVersion::new(1, 0), Some("2027-01-01".to_string()));
157 let default = negotiator.negotiate(&request(None).await).unwrap();
158 assert_eq!(default.selected, ApiVersion::new(2, 0));
159 let old = negotiator.negotiate(&request(Some("v1")).await).unwrap();
160 assert!(old.deprecated);
161 assert_eq!(old.sunset.as_deref(), Some("2027-01-01"));
162 }
163
164 #[tokio::test]
165 async fn rejects_invalid_and_unsupported_versions() {
166 let negotiator = VersionNegotiator::new([ApiVersion::new(1, 0)]);
167 assert_eq!(
168 negotiator.negotiate(&request(Some("bad")).await),
169 Err(VersionError::Invalid)
170 );
171 assert_eq!(
172 negotiator.negotiate(&request(Some("v3")).await),
173 Err(VersionError::Unsupported)
174 );
175 assert_eq!(
176 negotiator.negotiate(&request(None).await),
177 Err(VersionError::Missing)
178 );
179 }
180}