hyperx/header/common/
range.rs

1use std::fmt::{self, Display};
2use std::str::FromStr;
3
4use header::{Header, RawLike};
5use header::parsing::{from_one_raw_str};
6
7/// `Range` header, defined in [RFC7233](https://tools.ietf.org/html/rfc7233#section-3.1)
8///
9/// The "Range" header field on a GET request modifies the method
10/// semantics to request transfer of only one or more subranges of the
11/// selected representation data, rather than the entire selected
12/// representation data.
13///
14/// # ABNF
15///
16/// ```text
17/// Range = byte-ranges-specifier / other-ranges-specifier
18/// other-ranges-specifier = other-range-unit "=" other-range-set
19/// other-range-set = 1*VCHAR
20///
21/// bytes-unit = "bytes"
22///
23/// byte-ranges-specifier = bytes-unit "=" byte-range-set
24/// byte-range-set = 1#(byte-range-spec / suffix-byte-range-spec)
25/// byte-range-spec = first-byte-pos "-" [last-byte-pos]
26/// first-byte-pos = 1*DIGIT
27/// last-byte-pos = 1*DIGIT
28/// ```
29///
30/// # Example values
31///
32/// * `bytes=1000-`
33/// * `bytes=-2000`
34/// * `bytes=0-1,30-40`
35/// * `bytes=0-10,20-90,-100`
36/// * `custom_unit=0-123`
37/// * `custom_unit=xxx-yyy`
38///
39/// # Examples
40///
41/// ```
42/// # extern crate http;
43/// use hyperx::header::{Range, ByteRangeSpec, TypedHeaders};
44///
45/// let mut headers = http::HeaderMap::new();
46/// headers.encode(&Range::Bytes(
47///     vec![ByteRangeSpec::FromTo(1, 100), ByteRangeSpec::AllFrom(200)]
48/// ));
49///
50/// headers.clear();
51/// headers.encode(&Range::Unregistered("letters".to_owned(), "a-f".to_owned()));
52/// ```
53///
54/// ```
55/// # extern crate http;
56/// use hyperx::header::{Range, TypedHeaders};
57///
58/// let mut headers = http::HeaderMap::new();
59/// headers.encode(&Range::bytes(1, 100));
60///
61/// headers.clear();
62/// headers.encode(&Range::bytes_multi(vec![(1, 100), (200, 300)]));
63/// ```
64#[derive(PartialEq, Clone, Debug)]
65pub enum Range {
66    /// Byte range
67    Bytes(Vec<ByteRangeSpec>),
68    /// Custom range, with unit not registered at IANA
69    /// (`other-range-unit`: String , `other-range-set`: String)
70    Unregistered(String, String)
71}
72
73/// Each `Range::Bytes` header can contain one or more `ByteRangeSpecs`.
74/// Each `ByteRangeSpec` defines a range of bytes to fetch
75#[derive(PartialEq, Clone, Debug)]
76pub enum ByteRangeSpec {
77    /// Get all bytes between x and y ("x-y")
78    FromTo(u64, u64),
79    /// Get all bytes starting from x ("x-")
80    AllFrom(u64),
81    /// Get last x bytes ("-x")
82    Last(u64)
83}
84
85impl ByteRangeSpec {
86    /// Given the full length of the entity, attempt to normalize the byte range
87    /// into an satisfiable end-inclusive (from, to) range.
88    ///
89    /// The resulting range is guaranteed to be a satisfiable range within the bounds
90    /// of `0 <= from <= to < full_length`.
91    ///
92    /// If the byte range is deemed unsatisfiable, `None` is returned.
93    /// An unsatisfiable range is generally cause for a server to either reject
94    /// the client request with a `416 Range Not Satisfiable` status code, or to
95    /// simply ignore the range header and serve the full entity using a `200 OK`
96    /// status code.
97    ///
98    /// This function closely follows [RFC 7233][1] section 2.1.
99    /// As such, it considers ranges to be satisfiable if they meet the following
100    /// conditions:
101    ///
102    /// > If a valid byte-range-set includes at least one byte-range-spec with
103    /// a first-byte-pos that is less than the current length of the
104    /// representation, or at least one suffix-byte-range-spec with a
105    /// non-zero suffix-length, then the byte-range-set is satisfiable.
106    /// Otherwise, the byte-range-set is unsatisfiable.
107    ///
108    /// The function also computes remainder ranges based on the RFC:
109    ///
110    /// > If the last-byte-pos value is
111    /// absent, or if the value is greater than or equal to the current
112    /// length of the representation data, the byte range is interpreted as
113    /// the remainder of the representation (i.e., the server replaces the
114    /// value of last-byte-pos with a value that is one less than the current
115    /// length of the selected representation).
116    ///
117    /// [1]: https://tools.ietf.org/html/rfc7233
118    pub fn to_satisfiable_range(&self, full_length: u64) -> Option<(u64, u64)> {
119        // If the full length is zero, there is no satisfiable end-inclusive range.
120        if full_length == 0 {
121            return None;
122        }
123        match self {
124            &ByteRangeSpec::FromTo(from, to) => {
125                if from < full_length && from <= to {
126                    Some((from, ::std::cmp::min(to, full_length - 1)))
127                } else {
128                    None
129                }
130            },
131            &ByteRangeSpec::AllFrom(from) => {
132                if from < full_length {
133                    Some((from, full_length - 1))
134                } else {
135                    None
136                }
137            },
138            &ByteRangeSpec::Last(last) => {
139                if last > 0 {
140                    // From the RFC: If the selected representation is shorter
141                    // than the specified suffix-length,
142                    // the entire representation is used.
143                    if last > full_length {
144                        Some((0, full_length - 1))
145                    } else {
146                        Some((full_length - last, full_length - 1))
147                    }
148                } else {
149                    None
150                }
151            }
152        }
153    }
154}
155
156impl Range {
157    /// Get the most common byte range header ("bytes=from-to")
158    pub fn bytes(from: u64, to: u64) -> Range {
159        Range::Bytes(vec![ByteRangeSpec::FromTo(from, to)])
160    }
161
162    /// Get byte range header with multiple subranges
163    /// ("bytes=from1-to1,from2-to2,fromX-toX")
164    pub fn bytes_multi(ranges: Vec<(u64, u64)>) -> Range {
165        Range::Bytes(ranges.iter().map(|r| ByteRangeSpec::FromTo(r.0, r.1)).collect())
166    }
167}
168
169impl fmt::Display for ByteRangeSpec {
170    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
171        match *self {
172            ByteRangeSpec::FromTo(from, to) => write!(f, "{}-{}", from, to),
173            ByteRangeSpec::Last(pos) => write!(f, "-{}", pos),
174            ByteRangeSpec::AllFrom(pos) => write!(f, "{}-", pos),
175        }
176    }
177}
178
179impl fmt::Display for Range {
180    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
181        match *self {
182            Range::Bytes(ref ranges) => {
183                write!(f, "bytes=")?;
184
185                for (i, range) in ranges.iter().enumerate() {
186                    if i != 0 {
187                        f.write_str(",")?;
188                    }
189                    Display::fmt(range, f)?;
190                }
191                Ok(())
192            },
193            Range::Unregistered(ref unit, ref range_str) => {
194                write!(f, "{}={}", unit, range_str)
195            },
196        }
197    }
198}
199
200impl FromStr for Range {
201    type Err = ::Error;
202
203    fn from_str(s: &str) -> ::Result<Range> {
204        let mut iter = s.splitn(2, '=');
205
206        match (iter.next(), iter.next()) {
207            (Some("bytes"), Some(ranges)) => {
208                let ranges = from_comma_delimited(ranges);
209                if ranges.is_empty() {
210                    return Err(::Error::Header);
211                }
212                Ok(Range::Bytes(ranges))
213            }
214            (Some(unit), Some(range_str)) if unit != "" && range_str != "" => {
215                Ok(Range::Unregistered(unit.to_owned(), range_str.to_owned()))
216
217            },
218            _ => Err(::Error::Header)
219        }
220    }
221}
222
223impl FromStr for ByteRangeSpec {
224    type Err = ::Error;
225
226    fn from_str(s: &str) -> ::Result<ByteRangeSpec> {
227        let mut parts = s.splitn(2, '-');
228
229        match (parts.next(), parts.next()) {
230            (Some(""), Some(end)) => {
231                end.parse().or(Err(::Error::Header)).map(ByteRangeSpec::Last)
232            },
233            (Some(start), Some("")) => {
234                start.parse().or(Err(::Error::Header)).map(ByteRangeSpec::AllFrom)
235            },
236            (Some(start), Some(end)) => {
237                match (start.parse(), end.parse()) {
238                    (Ok(start), Ok(end)) if start <= end => Ok(ByteRangeSpec::FromTo(start, end)),
239                    _ => Err(::Error::Header)
240                }
241            },
242            _ => Err(::Error::Header)
243        }
244    }
245}
246
247fn from_comma_delimited<T: FromStr>(s: &str) -> Vec<T> {
248    s.split(',')
249        .filter_map(|x| match x.trim() {
250            "" => None,
251            y => Some(y)
252        })
253        .filter_map(|x| x.parse().ok())
254        .collect()
255}
256
257impl Header for Range {
258
259    fn header_name() -> &'static str {
260        static NAME: &'static str = "Range";
261        NAME
262    }
263
264    fn parse_header<'a, T>(raw: &'a T) -> ::Result<Range>
265    where T: RawLike<'a>
266    {
267        from_one_raw_str(raw)
268    }
269
270    fn fmt_header(&self, f: &mut ::header::Formatter) -> fmt::Result {
271        f.fmt_line(self)
272    }
273
274}
275
276#[cfg(test)]
277mod tests {
278    use super::{ByteRangeSpec, Range};
279    use header::{Header, Raw};
280
281    #[test]
282    fn test_parse_bytes_range_valid() {
283        let w: Raw = "bytes=1-100".into();
284        let r: Range = Header::parse_header(&w).unwrap();
285        let w: Raw = "bytes=1-100,-".into();
286        let r2: Range = Header::parse_header(&w).unwrap();
287        let r3 = Range::bytes(1, 100);
288        assert_eq!(r, r2);
289        assert_eq!(r2, r3);
290
291        let w: Raw = "bytes=1-100,200-".into();
292        let r: Range = Header::parse_header(&w).unwrap();
293        let w: Raw = "bytes= 1-100 , 101-xxx,  200- ".into();
294        let r2: Range = Header::parse_header(&w).unwrap();
295        let r3 =  Range::Bytes(
296            vec![ByteRangeSpec::FromTo(1, 100), ByteRangeSpec::AllFrom(200)]
297        );
298        assert_eq!(r, r2);
299        assert_eq!(r2, r3);
300
301        let w: Raw = "bytes=1-100,-100".into();
302        let r: Range = Header::parse_header(&w).unwrap();
303        let w: Raw = "bytes=1-100, ,,-100".into();
304        let r2: Range = Header::parse_header(&w).unwrap();
305        let r3 =  Range::Bytes(
306            vec![ByteRangeSpec::FromTo(1, 100), ByteRangeSpec::Last(100)]
307        );
308        assert_eq!(r, r2);
309        assert_eq!(r2, r3);
310
311        let w: Raw = "custom=1-100,-100".into();
312        let r: Range = Header::parse_header(&w).unwrap();
313        let r2 =  Range::Unregistered("custom".to_owned(), "1-100,-100".to_owned());
314        assert_eq!(r, r2);
315
316    }
317
318    #[test]
319    fn test_parse_unregistered_range_valid() {
320        let w: Raw = "custom=1-100,-100".into();
321        let r: Range = Header::parse_header(&w).unwrap();
322        let r2 =  Range::Unregistered("custom".to_owned(), "1-100,-100".to_owned());
323        assert_eq!(r, r2);
324
325        let w: Raw = "custom=abcd".into();
326        let r: Range = Header::parse_header(&w).unwrap();
327        let r2 =  Range::Unregistered("custom".to_owned(), "abcd".to_owned());
328        assert_eq!(r, r2);
329
330        let w: Raw = "custom=xxx-yyy".into();
331        let r: Range = Header::parse_header(&w).unwrap();
332        let r2 =  Range::Unregistered("custom".to_owned(), "xxx-yyy".to_owned());
333        assert_eq!(r, r2);
334    }
335
336    #[test]
337    fn test_parse_invalid() {
338        let w: Raw = "bytes=1-a,-".into();
339        let r: ::Result<Range> = Header::parse_header(&w);
340        assert_eq!(r.ok(), None);
341
342        let w: Raw = "bytes=1-2-3".into();
343        let r: ::Result<Range> = Header::parse_header(&w);
344        assert_eq!(r.ok(), None);
345
346        let w: Raw = "abc".into();
347        let r: ::Result<Range> = Header::parse_header(&w);
348        assert_eq!(r.ok(), None);
349
350        let w: Raw = "bytes=1-100=".into();
351        let r: ::Result<Range> = Header::parse_header(&w);
352        assert_eq!(r.ok(), None);
353
354        let w: Raw = "bytes=".into();
355        let r: ::Result<Range> = Header::parse_header(&w);
356        assert_eq!(r.ok(), None);
357
358        let w: Raw = "custom=".into();
359        let r: ::Result<Range> = Header::parse_header(&w);
360        assert_eq!(r.ok(), None);
361
362        let w: Raw = "=1-100".into();
363        let r: ::Result<Range> = Header::parse_header(&w);
364        assert_eq!(r.ok(), None);
365    }
366
367    #[cfg(feature = "headers")]
368    #[test]
369    fn test_fmt() {
370        use header::Headers;
371
372        let mut headers = Headers::new();
373
374        headers.set(
375            Range::Bytes(
376                vec![ByteRangeSpec::FromTo(0, 1000), ByteRangeSpec::AllFrom(2000)]
377            ));
378        assert_eq!(&headers.to_string(), "Range: bytes=0-1000,2000-\r\n");
379
380        headers.clear();
381        headers.set(Range::Bytes(vec![]));
382
383        assert_eq!(&headers.to_string(), "Range: bytes=\r\n");
384
385        headers.clear();
386        headers.set(Range::Unregistered("custom".to_owned(), "1-xxx".to_owned()));
387
388        assert_eq!(&headers.to_string(), "Range: custom=1-xxx\r\n");
389    }
390
391    #[test]
392    fn test_byte_range_spec_to_satisfiable_range() {
393        assert_eq!(Some((0, 0)), ByteRangeSpec::FromTo(0, 0).to_satisfiable_range(3));
394        assert_eq!(Some((1, 2)), ByteRangeSpec::FromTo(1, 2).to_satisfiable_range(3));
395        assert_eq!(Some((1, 2)), ByteRangeSpec::FromTo(1, 5).to_satisfiable_range(3));
396        assert_eq!(None, ByteRangeSpec::FromTo(3, 3).to_satisfiable_range(3));
397        assert_eq!(None, ByteRangeSpec::FromTo(2, 1).to_satisfiable_range(3));
398        assert_eq!(None, ByteRangeSpec::FromTo(0, 0).to_satisfiable_range(0));
399
400        assert_eq!(Some((0, 2)), ByteRangeSpec::AllFrom(0).to_satisfiable_range(3));
401        assert_eq!(Some((2, 2)), ByteRangeSpec::AllFrom(2).to_satisfiable_range(3));
402        assert_eq!(None, ByteRangeSpec::AllFrom(3).to_satisfiable_range(3));
403        assert_eq!(None, ByteRangeSpec::AllFrom(5).to_satisfiable_range(3));
404        assert_eq!(None, ByteRangeSpec::AllFrom(0).to_satisfiable_range(0));
405
406        assert_eq!(Some((1, 2)), ByteRangeSpec::Last(2).to_satisfiable_range(3));
407        assert_eq!(Some((2, 2)), ByteRangeSpec::Last(1).to_satisfiable_range(3));
408        assert_eq!(Some((0, 2)), ByteRangeSpec::Last(5).to_satisfiable_range(3));
409        assert_eq!(None, ByteRangeSpec::Last(0).to_satisfiable_range(3));
410        assert_eq!(None, ByteRangeSpec::Last(2).to_satisfiable_range(0));
411    }
412}
413
414bench_header!(bytes_multi, Range, { vec![b"bytes=1-1001,2001-3001,10001-".to_vec()]});
415bench_header!(custom_unit, Range, { vec![b"other=0-100000".to_vec()]});
416
417standard_header!(Range, RANGE);
hyperx/header/common/range.rs

hyperx/header/common/
range.rs
