feat: add If-Range header support

Add parsing and evaluation of the If-Range header (RFC 9110 Section
13.1.5). When a client sends If-Range alongside Range, the server must
check whether the validator (Last-Modified date or ETag) still matches
the current representation. If it does not match, the Range header must
be ignored and the full representation served.

The IfRange type supports both date and entity-tag validators, with
strong ETag comparison per RFC 9110 Section 8.8.3.2. An axum extractor
is provided behind the `axum` feature flag, returning Ok(None) for
missing or unparseable If-Range headers.

Author: paolobarbolini

src/headers/if_range.rs

@@ -0,0 +1,131 @@
+#[cfg(feature = "axum")]
+use std::convert::Infallible;
+use std::str::FromStr;
+
+use http::HeaderValue;
+
+use crate::headers::range::HttpRange;
+
+/// A typed HTTP `If-Range` header.
+///
+/// Per [RFC 9110 Section 13.1.5], `If-Range` can contain either an HTTP-date
+/// or an entity-tag. When present alongside a `Range` header, the server must
+/// evaluate the validator against the current representation:
+///
+/// - If the validator **matches**, the `Range` is honored (206 Partial Content).
+/// - If the validator **does not match**, the `Range` is ignored and the full
+///   representation is served (200 OK).
+///
+/// [RFC 9110 Section 13.1.5]: https://www.rfc-editor.org/rfc/rfc9110#section-13.1.5
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum IfRange {
+    /// An HTTP-date validator (the raw header value, to be compared with `Last-Modified`).
+    Date(HeaderValue),
+    /// An entity-tag validator (the raw header value, to be compared with `ETag`).
+    ETag(HeaderValue),
+}
+
+impl IfRange {
+    /// Evaluates the `If-Range` condition and returns the [`HttpRange`] only if
+    /// the condition holds.
+    ///
+    /// - `range`: the parsed `Range` header value.
+    /// - `last_modified`: the current `Last-Modified` header of the representation.
+    /// - `etag`: the current `ETag` header of the representation.
+    ///
+    /// Returns `Some(range)` if the validator matches (the range should be
+    /// honored), or `None` if it does not (the full representation should be
+    /// served).
+    ///
+    /// Per [RFC 9110 Section 13.1.5], the comparison uses the raw header values:
+    /// - For dates, the `If-Range` value must be an **exact byte-for-byte match**
+    ///   of the `Last-Modified` header value.
+    /// - For entity-tags, the `If-Range` value must be a **strong comparison**
+    ///   match against the `ETag` header value. Weak entity-tags never match.
+    ///
+    /// [RFC 9110 Section 13.1.5]: https://www.rfc-editor.org/rfc/rfc9110#section-13.1.5
+    pub fn evaluate(
+        &self,
+        range: HttpRange,
+        last_modified: Option<&HeaderValue>,
+        etag: Option<&HeaderValue>,
+    ) -> Option<HttpRange> {
+        let matches = match self {
+            IfRange::Date(date) => last_modified.is_some_and(|lm| lm == date),
+            IfRange::ETag(tag) => etag.is_some_and(|et| strong_etag_eq(tag, et)),
+        };
+
+        if matches { Some(range) } else { None }
+    }
+}
+
+/// Performs a strong comparison of two entity-tags.
+///
+/// Per [RFC 9110 Section 8.8.3.2], two entity-tags are strongly equivalent if
+/// both are **not** weak and their opaque-tags match character by character.
+///
+/// [RFC 9110 Section 8.8.3.2]: https://www.rfc-editor.org/rfc/rfc9110#section-8.8.3.2
+fn strong_etag_eq(a: &HeaderValue, b: &HeaderValue) -> bool {
+    let a = a.as_bytes();
+    let b = b.as_bytes();
+
+    // Weak tags (W/"...") never match in a strong comparison
+    if a.starts_with(b"W/") || b.starts_with(b"W/") {
+        return false;
+    }
+
+    a == b
+}
+
+impl FromStr for IfRange {
+    type Err = InvalidIfRange;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        let s = s.trim();
+        if s.is_empty() {
+            return Err(InvalidIfRange);
+        }
+
+        let value = HeaderValue::from_str(s).map_err(|_| InvalidIfRange)?;
+
+        // Per RFC 9110 Section 13.1.5, the field value is either an entity-tag
+        // or an HTTP-date. Entity-tags start with `"` or `W/"`.
+        if s.starts_with('"') || s.starts_with("W/\"") {
+            Ok(IfRange::ETag(value))
+        } else {
+            Ok(IfRange::Date(value))
+        }
+    }
+}
+
+impl TryFrom<&HeaderValue> for IfRange {
+    type Error = InvalidIfRange;
+
+    fn try_from(value: &HeaderValue) -> Result<Self, Self::Error> {
+        value.to_str().map_err(|_| InvalidIfRange)?.parse::<Self>()
+    }
+}
+
+/// An error returned when parsing an `If-Range` header fails.
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+#[error("Invalid If-Range header")]
+pub struct InvalidIfRange;
+
+#[cfg(feature = "axum")]
+impl<S> axum_core::extract::OptionalFromRequestParts<S> for IfRange
+where
+    S: Send + Sync,
+{
+    type Rejection = Infallible;
+
+    async fn from_request_parts(
+        parts: &mut http::request::Parts,
+        _state: &S,
+    ) -> Result<Option<Self>, Self::Rejection> {
+        let if_range = parts
+            .headers
+            .get(http::header::IF_RANGE)
+            .and_then(|v| IfRange::try_from(v).ok());
+        Ok(if_range)
+    }
+}

src/headers/mod.rs

@@ -5,6 +5,7 @@ use std::{
 };
 
 pub mod content_range;
+pub mod if_range;
 pub mod range;
 #[cfg(test)]
 mod tests;

src/headers/tests.rs

@@ -599,3 +599,137 @@ mod serve_file {
         assert!(result.is_err());
     }
 }
+
+#[cfg(test)]
+mod if_range {
+    use http::HeaderValue;
+
+    use crate::headers::{if_range::IfRange, range::HttpRange};
+
+    #[test]
+    fn parse_date() {
+        let ir: IfRange = "Sun, 05 Apr 2026 04:49:21 GMT".parse().unwrap();
+        assert!(matches!(ir, IfRange::Date(_)));
+    }
+
+    #[test]
+    fn parse_strong_etag() {
+        let ir: IfRange = "\"abc123\"".parse().unwrap();
+        assert!(matches!(ir, IfRange::ETag(_)));
+    }
+
+    #[test]
+    fn parse_weak_etag() {
+        let ir: IfRange = "W/\"abc123\"".parse().unwrap();
+        assert!(matches!(ir, IfRange::ETag(_)));
+    }
+
+    #[test]
+    fn empty_rejected() {
+        assert!("".parse::<IfRange>().is_err());
+    }
+
+    #[test]
+    fn whitespace_only_rejected() {
+        assert!("   ".parse::<IfRange>().is_err());
+    }
+
+    #[test]
+    fn date_matches_last_modified() {
+        let ir: IfRange = "Sun, 05 Apr 2026 04:49:21 GMT".parse().unwrap();
+        let lm = HeaderValue::from_static("Sun, 05 Apr 2026 04:49:21 GMT");
+        let range = HttpRange::StartingPoint(0);
+
+        assert_eq!(ir.evaluate(range, Some(&lm), None), Some(range));
+    }
+
+    #[test]
+    fn date_does_not_match_different_last_modified() {
+        let ir: IfRange = "Mon, 01 Jan 2024 00:00:00 GMT".parse().unwrap();
+        let lm = HeaderValue::from_static("Sun, 05 Apr 2026 04:49:21 GMT");
+        let range = HttpRange::StartingPoint(0);
+
+        assert_eq!(ir.evaluate(range, Some(&lm), None), None);
+    }
+
+    #[test]
+    fn date_does_not_match_missing_last_modified() {
+        let ir: IfRange = "Sun, 05 Apr 2026 04:49:21 GMT".parse().unwrap();
+        let range = HttpRange::StartingPoint(0);
+
+        assert_eq!(ir.evaluate(range, None, None), None);
+    }
+
+    #[test]
+    fn strong_etag_matches() {
+        let ir: IfRange = "\"abc123\"".parse().unwrap();
+        let etag = HeaderValue::from_static("\"abc123\"");
+        let range = HttpRange::StartingPoint(0);
+
+        assert_eq!(ir.evaluate(range, None, Some(&etag)), Some(range));
+    }
+
+    #[test]
+    fn strong_etag_does_not_match_different() {
+        let ir: IfRange = "\"abc123\"".parse().unwrap();
+        let etag = HeaderValue::from_static("\"xyz789\"");
+        let range = HttpRange::StartingPoint(0);
+
+        assert_eq!(ir.evaluate(range, None, Some(&etag)), None);
+    }
+
+    #[test]
+    fn strong_etag_does_not_match_missing() {
+        let ir: IfRange = "\"abc123\"".parse().unwrap();
+        let range = HttpRange::StartingPoint(0);
+
+        assert_eq!(ir.evaluate(range, None, None), None);
+    }
+
+    #[test]
+    fn weak_etag_never_matches_in_strong_comparison() {
+        let ir: IfRange = "W/\"abc123\"".parse().unwrap();
+        let etag = HeaderValue::from_static("W/\"abc123\"");
+        let range = HttpRange::StartingPoint(0);
+
+        assert_eq!(ir.evaluate(range, None, Some(&etag)), None);
+    }
+
+    #[test]
+    fn weak_if_range_does_not_match_strong_etag() {
+        let ir: IfRange = "W/\"abc123\"".parse().unwrap();
+        let etag = HeaderValue::from_static("\"abc123\"");
+        let range = HttpRange::StartingPoint(0);
+
+        assert_eq!(ir.evaluate(range, None, Some(&etag)), None);
+    }
+
+    #[test]
+    fn strong_if_range_does_not_match_weak_etag() {
+        let ir: IfRange = "\"abc123\"".parse().unwrap();
+        let etag = HeaderValue::from_static("W/\"abc123\"");
+        let range = HttpRange::StartingPoint(0);
+
+        assert_eq!(ir.evaluate(range, None, Some(&etag)), None);
+    }
+
+    #[test]
+    fn date_ignores_etag() {
+        let ir: IfRange = "Sun, 05 Apr 2026 04:49:21 GMT".parse().unwrap();
+        let etag = HeaderValue::from_static("\"abc123\"");
+        let range = HttpRange::StartingPoint(0);
+
+        // Date-based If-Range only checks Last-Modified, not ETag
+        assert_eq!(ir.evaluate(range, None, Some(&etag)), None);
+    }
+
+    #[test]
+    fn etag_ignores_last_modified() {
+        let ir: IfRange = "\"abc123\"".parse().unwrap();
+        let lm = HeaderValue::from_static("Sun, 05 Apr 2026 04:49:21 GMT");
+        let range = HttpRange::StartingPoint(0);
+
+        // ETag-based If-Range only checks ETag, not Last-Modified
+        assert_eq!(ir.evaluate(range, Some(&lm), None), None);
+    }
+}