socle 0.1.1

Opinionated axum service bootstrap: telemetry, database, rate limiting, and shutdown in one builder
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

//! ETag / conditional-request helpers.

pub use api_bones::etag::{ETag, IfMatch, IfNoneMatch, ParseETagError};

use axum::http::HeaderMap;
use chrono::{DateTime, Utc};

use crate::ApiError;

/// Derive a weak [`ETag`] from an `updated_at` timestamp.
pub fn etag_from_updated_at(updated_at: DateTime<Utc>) -> ETag {
    let millis = updated_at.timestamp_millis();
    ETag::weak(format!("{millis:x}"))
}

/// Validate the `If-Match` request header against a current [`ETag`].
pub fn check_if_match(headers: &HeaderMap, current_etag: &ETag) -> Result<(), ApiError> {
    let raw = match headers.get(axum::http::header::IF_MATCH) {
        None => {
            let mut err = ApiError::new(
                api_bones::error::ErrorCode::BadRequest,
                "If-Match header is required",
            );
            err.status = 428;
            err.title = "Precondition Required".to_owned();
            return Err(err);
        }
        Some(v) => v
            .to_str()
            .map_err(|_| ApiError::bad_request("If-Match header is not valid ASCII"))?,
    };

    let trimmed = raw.trim();
    let matched = if trimmed == "*" {
        true
    } else {
        let tags = ETag::parse_list(trimmed)
            .map_err(|e| ApiError::bad_request(format!("If-Match header is malformed: {e}")))?;
        tags.iter().any(|t| t.matches_weak(current_etag))
    };

    if matched {
        Ok(())
    } else {
        let mut err = ApiError::new(
            api_bones::error::ErrorCode::BadRequest,
            "ETag does not match; the resource has been modified",
        );
        err.status = 412;
        err.title = "Precondition Failed".to_owned();
        Err(err)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use axum::http::HeaderMap;
    use chrono::TimeZone as _;

    fn headers_with(name: &str, value: &str) -> HeaderMap {
        let mut h = HeaderMap::new();
        h.insert(
            axum::http::HeaderName::from_bytes(name.as_bytes()).unwrap(),
            axum::http::HeaderValue::from_str(value).unwrap(),
        );
        h
    }

    #[test]
    fn etag_from_updated_at_is_deterministic() {
        let ts = chrono::Utc.with_ymd_and_hms(2024, 1, 1, 0, 0, 0).unwrap();
        let a = etag_from_updated_at(ts);
        let b = etag_from_updated_at(ts);
        assert_eq!(a.to_string(), b.to_string());
        assert!(a.weak);
    }

    #[test]
    fn etag_from_updated_at_different_times_differ() {
        let t1 = chrono::Utc.with_ymd_and_hms(2024, 1, 1, 0, 0, 0).unwrap();
        let t2 = chrono::Utc.with_ymd_and_hms(2024, 1, 2, 0, 0, 0).unwrap();
        assert_ne!(
            etag_from_updated_at(t1).to_string(),
            etag_from_updated_at(t2).to_string()
        );
    }

    #[test]
    fn check_if_match_missing_header_returns_428() {
        let current = ETag::strong("abc".to_string());
        let err = check_if_match(&HeaderMap::new(), &current).unwrap_err();
        assert_eq!(err.status, 428);
    }

    #[test]
    fn check_if_match_wildcard_always_matches() {
        let current = ETag::strong("abc".to_string());
        assert!(check_if_match(&headers_with("if-match", "*"), &current).is_ok());
    }

    #[test]
    fn check_if_match_matching_etag_succeeds() {
        let ts = chrono::Utc.with_ymd_and_hms(2024, 6, 1, 0, 0, 0).unwrap();
        let current = etag_from_updated_at(ts);
        let tag_str = current.to_string();
        assert!(check_if_match(&headers_with("if-match", &tag_str), &current).is_ok());
    }

    #[test]
    fn check_if_match_mismatched_etag_returns_412() {
        let current = ETag::strong("current".to_string());
        let err = check_if_match(&headers_with("if-match", r#""other""#), &current).unwrap_err();
        assert_eq!(err.status, 412);
    }

    #[test]
    fn check_if_match_invalid_ascii_returns_400() {
        let current = ETag::strong("x".to_string());
        let mut h = HeaderMap::new();
        h.insert(
            "if-match",
            axum::http::HeaderValue::from_bytes(b"\xff\xfe").unwrap(),
        );
        let err = check_if_match(&h, &current).unwrap_err();
        assert_eq!(err.status, 400);
    }
}