Skip to main content

yaiko_core/
versioning.rs

1//! API version negotiation and compatibility metadata.
2
3use 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}