s4_server/
cors.rs

1//! v0.6 #38: Bucket CORS configuration + preflight matcher.
2//!
3//! S4-server に bucket-level CORS の **own state** を持たせる module。これまで
4//! `get_bucket_cors` / `put_bucket_cors` / `delete_bucket_cors` は backend (s3s
5//! framework) への passthrough だったが、本 module で S4 自身が
6//!
7//! - per-bucket の [`CorsConfig`] (= ordered list of [`CorsRule`])
8//! - rule 評価器 (S3 仕様準拠: 宣言順で先頭マッチ採用)
9//!
10//! を所有する。`crates/s4-server/src/service.rs` の CORS handler が `S4Service`
11//! 経由で [`CorsManager`] を呼び出して、AWS S3 wire-compat な PutBucketCors /
12//! GetBucketCors / DeleteBucketCors の振る舞いを実現する。
13//!
14//! ## scope (v0.6 #38)
15//!
16//! - in-memory only (single instance scope)。multi-instance replication は
17//!   将来 issue で扱う
18//! - `to_json` / `from_json` で snapshot を取る API は提供する。`main.rs` 側で
19//!   `--cors-state-file` flag で起動時に snapshot を load できる
20//! - **OPTIONS preflight routing は本 task の scope 外**。s3s framework は
21//!   OPTIONS verb を専用 handler として持たないため、実際の HTTP-level
22//!   preflight 応答 (Access-Control-Allow-* header の組み立て) は `routing.rs`
23//!   側で hyper-util listener intercept として wire する follow-up が必要。
24//!   本 module は match 評価エンジン (= [`CorsManager::match_preflight`]) と、
25//!   service.rs から呼べる public method ([`crate::S4Service::handle_preflight`])
26//!   を提供するところまで
27//!
28//! ## semantics
29//!
30//! - **rule 評価順序**: AWS S3 は rule を **宣言順** で評価し、最初にマッチ
31//!   した rule を採用する。同一 bucket に対する PutBucketCors は configuration
32//!   全体を **置き換える** (上書き)、partial update は無し
33//! - **wildcard `*`**: origin / method / header いずれも `*` 単独で「任意」を意
34//!   味する (S3 は per-component 部分マッチ wildcard `https://*.example.com` は
35//!   サポートしない — `*` は「すべて」のみ)。ただし AWS docs の最新版では
36//!   `https://*.example.com` 形式も受け付けるとあるので、本実装でも `*` を
37//!   single-segment glob として扱える [`matches_glob`] を提供する
38//! - **origin matching**: case-sensitive (scheme + host + port は RFC 6454 で
39//!   ASCII-lowercase 正規化対象だが、S3 は client が送ってきた string をその
40//!   ままバイト比較する仕様)
41//! - **method matching**: 大文字必須 (HTTP verb は uppercase)、exact match
42//! - **header matching**: case-insensitive (HTTP header name は RFC 7230 で
43//!   case-insensitive)
44
45use std::collections::HashMap;
46use std::sync::RwLock;
47
48use serde::{Deserialize, Serialize};
49
50/// v0.8.15 M-3: validation errors surfaced by [`CorsManager::validate`].
51#[derive(Debug, thiserror::Error)]
52pub enum CorsValidationError {
53    #[error(
54        "AllowedMethod {0:?} is not a valid AWS S3 CORS verb (must be one of GET / PUT / POST / DELETE / HEAD; `*` is rejected)"
55    )]
56    UnsupportedMethod(String),
57}
58
59/// 1つの CORS rule。AWS S3 `CORSRule` element に対応する。
60///
61/// `id` は rule の human-readable label (operator が trace 用に付ける)。
62/// `expose_headers` はレスポンスに含まれる header 名 — preflight ではなく
63/// **actual response** で使われる (`Access-Control-Expose-Headers`)。
64/// `max_age_seconds` は browser 側 preflight cache TTL。
65#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
66pub struct CorsRule {
67    /// `"*"` for any origin, or exact origin string like
68    /// `"https://example.com"`. Multiple values are evaluated as OR within
69    /// this rule.
70    pub allowed_origins: Vec<String>,
71    /// Uppercase HTTP verbs: `"GET"`, `"PUT"`, `"POST"`, `"DELETE"`,
72    /// `"HEAD"`. AWS S3 only allows this set; we don't validate (caller
73    /// is responsible).
74    pub allowed_methods: Vec<String>,
75    /// `"*"` or specific header names. Matched case-insensitively against
76    /// `Access-Control-Request-Headers` from the preflight request.
77    pub allowed_headers: Vec<String>,
78    /// Header names to expose in the actual response via
79    /// `Access-Control-Expose-Headers`. Empty = no header.
80    #[serde(default)]
81    pub expose_headers: Vec<String>,
82    /// `Access-Control-Max-Age` value (browser preflight cache TTL).
83    /// `None` = header omitted.
84    #[serde(default)]
85    pub max_age_seconds: Option<u32>,
86    /// Optional rule identifier (operator-supplied label).
87    #[serde(default)]
88    pub id: Option<String>,
89}
90
91/// Per-bucket CORS configuration (ordered list of rules).
92#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
93pub struct CorsConfig {
94    /// Rules in declaration order — first match wins (S3 spec).
95    pub rules: Vec<CorsRule>,
96}
97
98/// snapshot のシリアライズ format。`to_json` / `from_json` 用。
99#[derive(Debug, Default, Serialize, Deserialize)]
100struct CorsSnapshot {
101    by_bucket: HashMap<String, CorsConfig>,
102}
103
104/// per-bucket CORS configuration を一元管理する manager。
105///
106/// すべての書き込み (`put` / `delete`) は `RwLock` write 経由で atomic、
107/// すべての読み出し (`get` / `match_preflight`) は read 経由で `CorsConfig`
108/// の clone (or 派生 `CorsRule` の clone) を返す。
109#[derive(Debug, Default)]
110pub struct CorsManager {
111    by_bucket: RwLock<HashMap<String, CorsConfig>>,
112}
113
114impl CorsManager {
115    /// 空 manager。
116    #[must_use]
117    pub fn new() -> Self {
118        Self::default()
119    }
120
121    /// `put_bucket_cors` handler から呼ぶ。bucket の既存 configuration は
122    /// **完全に置き換える** (S3 spec: PutBucketCors は upsert ではなく replace)。
123    pub fn put(&self, bucket: &str, config: CorsConfig) {
124        crate::lock_recovery::recover_write(&self.by_bucket, "cors.by_bucket")
125            .insert(bucket.to_owned(), config);
126    }
127
128    /// v0.8.15 M-3: validate a `CorsConfig` against the AWS S3 spec
129    /// before persisting. Returns the typed validation error so the
130    /// listener can surface `InvalidArgument` (mirrors what AWS S3
131    /// does at PutBucketCors time, instead of silently accepting a
132    /// non-compliant rule and returning a 404-shaped preflight
133    /// behaviour later).
134    ///
135    /// Current rules:
136    ///
137    /// - `AllowedMethods` ⊆ `{GET, PUT, POST, DELETE, HEAD}`. AWS S3
138    ///   rejects every other verb and the `*` wildcard.
139    pub fn validate(config: &CorsConfig) -> Result<(), CorsValidationError> {
140        const VALID_METHODS: &[&str] = &["GET", "PUT", "POST", "DELETE", "HEAD"];
141        for rule in &config.rules {
142            for m in &rule.allowed_methods {
143                if !VALID_METHODS.contains(&m.as_str()) {
144                    return Err(CorsValidationError::UnsupportedMethod(m.clone()));
145                }
146            }
147        }
148        Ok(())
149    }
150
151    /// `get_bucket_cors` handler から呼ぶ。configuration が無ければ `None`
152    /// (handler 側で `NoSuchCORSConfiguration` 404 を返す材料)。
153    #[must_use]
154    pub fn get(&self, bucket: &str) -> Option<CorsConfig> {
155        crate::lock_recovery::recover_read(&self.by_bucket, "cors.by_bucket")
156            .get(bucket)
157            .cloned()
158    }
159
160    /// `delete_bucket_cors` handler から呼ぶ。bucket が無くても idempotent。
161    pub fn delete(&self, bucket: &str) {
162        crate::lock_recovery::recover_write(&self.by_bucket, "cors.by_bucket").remove(bucket);
163    }
164
165    /// snapshot を JSON 文字列にして返す。`--cors-state-file` 経路で
166    /// 起動時 dump-load を将来 wire するための hook。
167    pub fn to_json(&self) -> Result<String, serde_json::Error> {
168        let snap = CorsSnapshot {
169            by_bucket: crate::lock_recovery::recover_read(&self.by_bucket, "cors.by_bucket")
170                .clone(),
171        };
172        serde_json::to_string(&snap)
173    }
174
175    /// snapshot JSON から restore。起動時に `--cors-state-file` を読み込む
176    /// 経路で使える。
177    ///
178    /// v0.8.16 F-9: validate each restored config against the same
179    /// rules `PutBucketCors` enforces. Pre-F-9 a snapshot file with
180    /// `AllowedMethods: ["*"]` (the wildcard #139 prohibits) would
181    /// be silently restored and the `rule_matches_method` legacy
182    /// wildcard branch would honor it at preflight time. We now
183    /// surface `serde_json::Error` (custom-converted) on any
184    /// validation failure so the operator fixes the snapshot
185    /// before the listener serves traffic. Non-validation parse
186    /// errors propagate unchanged.
187    pub fn from_json(s: &str) -> Result<Self, serde_json::Error> {
188        let snap: CorsSnapshot = serde_json::from_str(s)?;
189        for cfg in snap.by_bucket.values() {
190            if let Err(e) = Self::validate(cfg) {
191                return Err(serde::de::Error::custom(format!(
192                    "CORS snapshot fails AWS S3 validation: {e}"
193                )));
194            }
195        }
196        Ok(Self {
197            by_bucket: RwLock::new(snap.by_bucket),
198        })
199    }
200
201    /// CORS preflight (OPTIONS) request を bucket の rule list に対して評価
202    /// する。S3 仕様通り、宣言順で **最初にマッチした rule** を返す。マッチ
203    /// しない / bucket に config が無い場合は `None`。
204    ///
205    /// rule マッチ条件 (AND):
206    /// 1. `origin` が `rule.allowed_origins` のどれか 1 つに [`matches_glob`] でマッチ
207    /// 2. `method` (uppercase) が `rule.allowed_methods` の exact-match 1 つに含まれる
208    /// 3. `request_headers` の **全要素** が `rule.allowed_headers` のいずれかに [`matches_glob`] (case-insensitive) でマッチ
209    #[must_use]
210    pub fn match_preflight(
211        &self,
212        bucket: &str,
213        origin: &str,
214        method: &str,
215        request_headers: &[String],
216    ) -> Option<CorsRule> {
217        let map = crate::lock_recovery::recover_read(&self.by_bucket, "cors.by_bucket");
218        let cfg = map.get(bucket)?;
219        for rule in &cfg.rules {
220            if !rule_matches_origin(rule, origin) {
221                continue;
222            }
223            if !rule_matches_method(rule, method) {
224                continue;
225            }
226            if !rule_matches_headers(rule, request_headers) {
227                continue;
228            }
229            return Some(rule.clone());
230        }
231        None
232    }
233}
234
235fn rule_matches_origin(rule: &CorsRule, origin: &str) -> bool {
236    rule.allowed_origins
237        .iter()
238        .any(|pat| matches_glob(pat, origin))
239}
240
241fn rule_matches_method(rule: &CorsRule, method: &str) -> bool {
242    // v0.8.16 F-9: the `*` wildcard is no longer recognised at
243    // runtime, mirroring the v0.8.15 #139 `PutBucketCors`
244    // validation. A pre-#139 deployment that persisted
245    // `AllowedMethods=["*"]` via snapshot would still preflight-
246    // match every verb at the matcher; that's the gap. AWS S3
247    // never recognised `*` as a verb wildcard — exact match only.
248    rule.allowed_methods.iter().any(|pat| pat == method)
249}
250
251fn rule_matches_headers(rule: &CorsRule, request_headers: &[String]) -> bool {
252    if request_headers.is_empty() {
253        return true;
254    }
255    request_headers.iter().all(|h| {
256        rule.allowed_headers
257            .iter()
258            .any(|pat| matches_glob_ci(pat, h))
259    })
260}
261
262/// AWS S3 CORS の `*` matching。
263///
264/// - `pattern == "*"` → 任意の `candidate` にマッチ (true)
265/// - それ以外は **exact byte equality** で比較
266///
267/// AWS docs は `https://*.example.com` 形式も受け付けるとあるが、`*` は
268/// segment 単位ではなく「全体のいずれか 1 つ」として S3 上で動くケースが
269/// 大半なので、本実装は wildcard を `*` 単独 token に限定する。case
270/// sensitivity は呼び出し側で制御 (origin は case-sensitive、header は
271/// [`matches_glob_ci`] 経由で case-insensitive)。
272#[must_use]
273pub fn matches_glob(pattern: &str, candidate: &str) -> bool {
274    if pattern == "*" {
275        return true;
276    }
277    pattern == candidate
278}
279
280/// case-insensitive 版の [`matches_glob`]。HTTP header name 用。
281#[must_use]
282pub fn matches_glob_ci(pattern: &str, candidate: &str) -> bool {
283    if pattern == "*" {
284        return true;
285    }
286    pattern.eq_ignore_ascii_case(candidate)
287}
288
289#[cfg(test)]
290mod tests {
291    use super::*;
292
293    fn rule(origins: &[&str], methods: &[&str], headers: &[&str]) -> CorsRule {
294        CorsRule {
295            allowed_origins: origins.iter().map(|s| (*s).to_owned()).collect(),
296            allowed_methods: methods.iter().map(|s| (*s).to_owned()).collect(),
297            allowed_headers: headers.iter().map(|s| (*s).to_owned()).collect(),
298            expose_headers: Vec::new(),
299            max_age_seconds: Some(3600),
300            id: None,
301        }
302    }
303
304    #[test]
305    fn matches_glob_wildcard_matches_anything() {
306        assert!(matches_glob("*", "https://example.com"));
307        assert!(matches_glob("*", ""));
308        assert!(matches_glob("*", "GET"));
309    }
310
311    #[test]
312    fn matches_glob_exact_match() {
313        assert!(matches_glob("https://example.com", "https://example.com"));
314        assert!(matches_glob("GET", "GET"));
315    }
316
317    #[test]
318    fn matches_glob_no_match() {
319        assert!(!matches_glob("https://example.com", "https://evil.com"));
320        assert!(!matches_glob("GET", "PUT"));
321    }
322
323    #[test]
324    fn matches_glob_origin_is_case_sensitive() {
325        // S3 origin matching is case-sensitive byte equality.
326        assert!(!matches_glob("https://Example.com", "https://example.com"));
327    }
328
329    #[test]
330    fn matches_glob_ci_header_is_case_insensitive() {
331        assert!(matches_glob_ci("Content-Type", "content-type"));
332        assert!(matches_glob_ci("X-Amz-Date", "x-amz-date"));
333        assert!(!matches_glob_ci("X-Other", "X-Different"));
334    }
335
336    #[test]
337    fn match_preflight_happy_path() {
338        let mgr = CorsManager::new();
339        mgr.put(
340            "b",
341            CorsConfig {
342                rules: vec![rule(
343                    &["https://app.example.com"],
344                    &["GET", "PUT"],
345                    &["Content-Type"],
346                )],
347            },
348        );
349        let m = mgr.match_preflight(
350            "b",
351            "https://app.example.com",
352            "PUT",
353            &["Content-Type".to_owned()],
354        );
355        assert!(m.is_some());
356        let rule = m.unwrap();
357        assert_eq!(rule.max_age_seconds, Some(3600));
358    }
359
360    #[test]
361    fn match_preflight_no_rule_for_bucket() {
362        let mgr = CorsManager::new();
363        let m = mgr.match_preflight("ghost", "https://anything", "GET", &[]);
364        assert!(m.is_none());
365    }
366
367    #[test]
368    fn match_preflight_method_not_allowed() {
369        let mgr = CorsManager::new();
370        mgr.put(
371            "b",
372            CorsConfig {
373                rules: vec![rule(&["*"], &["GET"], &["*"])],
374            },
375        );
376        // Rule allows GET only — DELETE preflight must miss.
377        assert!(
378            mgr.match_preflight("b", "https://x", "DELETE", &[])
379                .is_none()
380        );
381        // Sanity: GET still matches.
382        assert!(mgr.match_preflight("b", "https://x", "GET", &[]).is_some());
383    }
384
385    #[test]
386    fn match_preflight_origin_not_allowed() {
387        let mgr = CorsManager::new();
388        mgr.put(
389            "b",
390            CorsConfig {
391                rules: vec![rule(&["https://good.example.com"], &["GET"], &["*"])],
392            },
393        );
394        assert!(
395            mgr.match_preflight("b", "https://evil.example.com", "GET", &[])
396                .is_none()
397        );
398    }
399
400    #[test]
401    fn match_preflight_wildcard_origin() {
402        let mgr = CorsManager::new();
403        mgr.put(
404            "b",
405            CorsConfig {
406                rules: vec![rule(&["*"], &["GET"], &[])],
407            },
408        );
409        let m = mgr.match_preflight("b", "https://anywhere", "GET", &[]);
410        assert!(m.is_some());
411    }
412
413    #[test]
414    fn match_preflight_wildcard_header() {
415        let mgr = CorsManager::new();
416        mgr.put(
417            "b",
418            CorsConfig {
419                rules: vec![rule(&["*"], &["PUT"], &["*"])],
420            },
421        );
422        let m = mgr.match_preflight(
423            "b",
424            "https://x",
425            "PUT",
426            &["X-Custom-Header".to_owned(), "Content-Type".to_owned()],
427        );
428        assert!(m.is_some());
429    }
430
431    #[test]
432    fn match_preflight_first_matching_rule_wins() {
433        let mgr = CorsManager::new();
434        mgr.put(
435            "b",
436            CorsConfig {
437                rules: vec![
438                    CorsRule {
439                        allowed_origins: vec!["*".into()],
440                        allowed_methods: vec!["GET".into()],
441                        allowed_headers: vec!["*".into()],
442                        expose_headers: Vec::new(),
443                        max_age_seconds: Some(60),
444                        id: Some("first".into()),
445                    },
446                    CorsRule {
447                        allowed_origins: vec!["*".into()],
448                        allowed_methods: vec!["GET".into()],
449                        allowed_headers: vec!["*".into()],
450                        expose_headers: Vec::new(),
451                        max_age_seconds: Some(7200),
452                        id: Some("second".into()),
453                    },
454                ],
455            },
456        );
457        let m = mgr
458            .match_preflight("b", "https://x", "GET", &[])
459            .expect("should match");
460        // First-match-wins: shorter max_age_seconds, id="first".
461        assert_eq!(m.id.as_deref(), Some("first"));
462        assert_eq!(m.max_age_seconds, Some(60));
463    }
464
465    #[test]
466    fn match_preflight_header_case_insensitive() {
467        let mgr = CorsManager::new();
468        mgr.put(
469            "b",
470            CorsConfig {
471                rules: vec![rule(&["*"], &["PUT"], &["Content-Type"])],
472            },
473        );
474        // request header sent in lowercase — must still match the
475        // CamelCase pattern (HTTP header names are case-insensitive).
476        let m = mgr.match_preflight("b", "https://x", "PUT", &["content-type".to_owned()]);
477        assert!(m.is_some());
478    }
479
480    #[test]
481    fn put_replaces_previous_config() {
482        let mgr = CorsManager::new();
483        mgr.put(
484            "b",
485            CorsConfig {
486                rules: vec![rule(&["https://a"], &["GET"], &["*"])],
487            },
488        );
489        mgr.put(
490            "b",
491            CorsConfig {
492                rules: vec![rule(&["https://b"], &["PUT"], &["*"])],
493            },
494        );
495        let cfg = mgr.get("b").expect("config present");
496        assert_eq!(cfg.rules.len(), 1);
497        assert_eq!(cfg.rules[0].allowed_origins, vec!["https://b".to_string()]);
498    }
499
500    #[test]
501    fn delete_is_idempotent() {
502        let mgr = CorsManager::new();
503        mgr.delete("never-existed"); // must not panic
504        mgr.put(
505            "b",
506            CorsConfig {
507                rules: vec![rule(&["*"], &["GET"], &[])],
508            },
509        );
510        mgr.delete("b");
511        assert!(mgr.get("b").is_none());
512    }
513
514    #[test]
515    fn json_round_trip() {
516        let mgr = CorsManager::new();
517        mgr.put(
518            "b",
519            CorsConfig {
520                rules: vec![CorsRule {
521                    allowed_origins: vec!["https://example.com".into()],
522                    allowed_methods: vec!["GET".into(), "PUT".into()],
523                    allowed_headers: vec!["Content-Type".into()],
524                    expose_headers: vec!["ETag".into()],
525                    max_age_seconds: Some(3600),
526                    id: Some("rule-1".into()),
527                }],
528            },
529        );
530        let json = mgr.to_json().expect("to_json");
531        let mgr2 = CorsManager::from_json(&json).expect("from_json");
532        assert_eq!(mgr.get("b"), mgr2.get("b"));
533    }
534
535    /// v0.8.4 #77 (audit H-8): a panic inside the `by_bucket` write
536    /// guard poisons the lock. `to_json` must recover via
537    /// [`crate::lock_recovery::recover_read`] and surface the data
538    /// instead of re-panicking on the SIGUSR1 dump-back path.
539    #[test]
540    fn cors_to_json_after_panic_recovers_via_poison() {
541        let mgr = std::sync::Arc::new(CorsManager::new());
542        mgr.put(
543            "b",
544            CorsConfig {
545                rules: vec![rule(&["*"], &["GET"], &[])],
546            },
547        );
548        let mgr_cl = std::sync::Arc::clone(&mgr);
549        let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
550            let mut g = mgr_cl.by_bucket.write().expect("clean lock");
551            g.entry("b2".into()).or_default();
552            panic!("force-poison");
553        }));
554        assert!(
555            mgr.by_bucket.is_poisoned(),
556            "write panic must poison by_bucket lock"
557        );
558        let json = mgr.to_json().expect("to_json after poison must succeed");
559        let mgr2 = CorsManager::from_json(&json).expect("from_json");
560        assert!(
561            mgr2.get("b").is_some(),
562            "recovered snapshot keeps original config"
563        );
564    }
565}
s4_server/cors.rs

s4_server/
cors.rs
