Skip to main content

shaul_core/
range.rs

1use serde::{Deserialize, Serialize};
2
3use crate::error::{Error, Result};
4
5/// A byte range with an exclusive end. Used for HTTP segments and resume
6/// manifests.
7#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
8pub struct ByteRange {
9    /// First byte included in the range.
10    pub start: u64,
11    /// Exclusive.
12    pub end: u64,
13}
14
15impl ByteRange {
16    /// Creates a half-open range, rejecting `start >= end`.
17    pub fn new(start: u64, end: u64) -> Result<Self> {
18        if start >= end {
19            return Err(Error::Other(format!("invalid byte range {start}..{end}")));
20        }
21        Ok(Self { start, end })
22    }
23
24    /// Number of bytes covered by the range.
25    pub fn len(&self) -> u64 {
26        self.end - self.start
27    }
28
29    /// Returns `true` when the range covers no bytes.
30    pub fn is_empty(&self) -> bool {
31        self.start >= self.end
32    }
33
34    /// Returns `true` if `other` lies entirely inside this range.
35    pub fn contains(&self, other: &ByteRange) -> bool {
36        self.start <= other.start && other.end <= self.end
37    }
38}
39
40/// Sort and coalesce overlapping or adjacent ranges.
41pub fn merge_ranges(mut ranges: Vec<ByteRange>) -> Vec<ByteRange> {
42    ranges.retain(|range| !range.is_empty());
43    ranges.sort_by_key(|range| range.start);
44    let mut merged: Vec<ByteRange> = Vec::with_capacity(ranges.len());
45    for range in ranges {
46        match merged.last_mut() {
47            Some(last) if range.start <= last.end => {
48                if range.end > last.end {
49                    last.end = range.end;
50                }
51            }
52            _ => merged.push(range),
53        }
54    }
55    merged
56}
57
58/// Complement of `completed` inside `0..total`.
59pub fn missing_ranges(total: u64, completed: &[ByteRange]) -> Vec<ByteRange> {
60    let completed = merge_ranges(completed.to_vec());
61    let mut missing = Vec::new();
62    let mut cursor = 0u64;
63    for range in completed {
64        if range.start > cursor
65            && let Ok(gap) = ByteRange::new(cursor, range.start.min(total))
66        {
67            missing.push(gap);
68        }
69        cursor = cursor.max(range.end);
70        if cursor >= total {
71            break;
72        }
73    }
74    if cursor < total
75        && let Ok(gap) = ByteRange::new(cursor, total)
76    {
77        missing.push(gap);
78    }
79    missing
80}
81
82/// Total number of bytes covered, counting overlapping ranges once.
83pub fn completed_bytes(completed: &[ByteRange]) -> u64 {
84    merge_ranges(completed.to_vec())
85        .iter()
86        .map(ByteRange::len)
87        .sum()
88}
89
90/// Drop or clamp ranges that extend past the known file length.
91pub fn clamp_to_len(ranges: &[ByteRange], len: u64) -> Vec<ByteRange> {
92    ranges
93        .iter()
94        .filter_map(|range| {
95            if range.start >= len {
96                None
97            } else {
98                ByteRange::new(range.start, range.end.min(len)).ok()
99            }
100        })
101        .collect()
102}
103
104/// Split a range into chunks of at most `chunk_size` bytes.
105pub fn split_range(range: ByteRange, chunk_size: u64) -> Vec<ByteRange> {
106    let chunk_size = chunk_size.max(1);
107    let mut chunks = Vec::new();
108    let mut start = range.start;
109    while start < range.end {
110        let end = (start + chunk_size).min(range.end);
111        if let Ok(chunk) = ByteRange::new(start, end) {
112            chunks.push(chunk);
113        }
114        start = end;
115    }
116    chunks
117}
118
119#[cfg(test)]
120mod tests {
121    use super::*;
122
123    #[test]
124    fn merges_adjacent_and_overlapping() {
125        let merged = merge_ranges(vec![
126            ByteRange::new(0, 10).unwrap(),
127            ByteRange::new(10, 20).unwrap(),
128            ByteRange::new(15, 25).unwrap(),
129            ByteRange::new(40, 50).unwrap(),
130        ]);
131        assert_eq!(
132            merged,
133            vec![
134                ByteRange::new(0, 25).unwrap(),
135                ByteRange::new(40, 50).unwrap()
136            ]
137        );
138    }
139
140    #[test]
141    fn computes_missing_ranges() {
142        let missing = missing_ranges(
143            100,
144            &[
145                ByteRange::new(10, 20).unwrap(),
146                ByteRange::new(50, 60).unwrap(),
147            ],
148        );
149        assert_eq!(
150            missing,
151            vec![
152                ByteRange::new(0, 10).unwrap(),
153                ByteRange::new(20, 50).unwrap(),
154                ByteRange::new(60, 100).unwrap()
155            ]
156        );
157    }
158
159    #[test]
160    fn splits_ranges() {
161        let chunks = split_range(ByteRange::new(0, 10).unwrap(), 4);
162        assert_eq!(
163            chunks,
164            vec![
165                ByteRange::new(0, 4).unwrap(),
166                ByteRange::new(4, 8).unwrap(),
167                ByteRange::new(8, 10).unwrap()
168            ]
169        );
170    }
171}