Skip to main content

shaul_core/
task.rs

1use std::collections::BTreeMap;
2use std::path::{Path, PathBuf};
3
4use serde::{Deserialize, Serialize};
5use url::Url;
6use uuid::Uuid;
7
8use crate::checksum::Checksum;
9use crate::header::RequestOptions;
10use crate::link::Link;
11use crate::range::{ByteRange, completed_bytes, merge_ranges};
12use crate::resource::Resource;
13use crate::util::now_ms;
14
15pub type TaskId = Uuid;
16
17pub const TASK_SCHEMA_VERSION: u32 = 1;
18
19#[derive(Clone, Debug, Serialize, Deserialize)]
20#[non_exhaustive]
21pub struct Task {
22    pub schema_version: u32,
23    pub id: TaskId,
24    pub link: Link,
25    #[serde(default)]
26    pub resource: Option<Resource>,
27    #[serde(default)]
28    pub backend: Option<String>,
29    pub destination: PathBuf,
30    pub options: TaskOptions,
31    pub state: TaskState,
32    #[serde(default)]
33    pub files: Vec<FileItem>,
34    #[serde(default)]
35    pub resume: Option<TaskResume>,
36    #[serde(default)]
37    pub error: Option<String>,
38    pub created_at_ms: u64,
39    pub updated_at_ms: u64,
40}
41
42impl Task {
43    pub fn new(link: Link, destination: PathBuf, options: TaskOptions) -> Self {
44        let now = now_ms();
45        Self {
46            schema_version: TASK_SCHEMA_VERSION,
47            id: Uuid::now_v7(),
48            link,
49            resource: None,
50            backend: None,
51            destination,
52            options,
53            state: TaskState::Pending,
54            files: Vec::new(),
55            resume: None,
56            error: None,
57            created_at_ms: now,
58            updated_at_ms: now,
59        }
60    }
61
62    pub fn touch(&mut self) {
63        self.updated_at_ms = now_ms();
64    }
65
66    pub fn key(&self) -> String {
67        format!(
68            "{}|{}",
69            self.link.canonical(),
70            self.destination.to_string_lossy()
71        )
72    }
73
74    pub fn set_resource(&mut self, resource: Resource) {
75        self.files = resource
76            .files
77            .iter()
78            .map(|file| FileItem {
79                path: file.path.clone(),
80                url: Some(file.url.clone()),
81                size: file.size,
82                downloaded: 0,
83                state: FileState::Pending,
84                checksum: file.checksum.clone(),
85                selected: true,
86            })
87            .collect();
88        self.resource = Some(resource);
89    }
90
91    /// Pull completed byte counts and final paths back from the resume
92    /// manifest so `status`/`list` show meaningful progress.
93    pub fn refresh_from_resume(&mut self) {
94        let Some(resume) = &self.resume else {
95            return;
96        };
97        for file in &mut self.files {
98            let Some(url) = &file.url else {
99                continue;
100            };
101            if let Some(entry) = resume.files.get(url.as_str()) {
102                file.downloaded = completed_bytes(&entry.completed);
103                if let Some(size) = entry.total_size {
104                    file.size = Some(size);
105                }
106                file.path = entry.final_path.clone();
107            }
108        }
109    }
110
111    pub fn total_bytes(&self) -> Option<u64> {
112        self.files
113            .iter()
114            .try_fold(0u64, |sum, file| file.size.map(|size| sum + size))
115    }
116
117    pub fn downloaded_bytes(&self) -> u64 {
118        self.files.iter().map(|file| file.downloaded).sum()
119    }
120}
121
122#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
123#[serde(rename_all = "snake_case")]
124#[non_exhaustive]
125pub enum TaskState {
126    Pending,
127    Running,
128    Paused,
129    Completed,
130    Failed,
131    Cancelled,
132}
133
134impl TaskState {
135    pub fn is_active(&self) -> bool {
136        matches!(self, Self::Pending | Self::Running | Self::Paused)
137    }
138}
139
140#[derive(Clone, Debug, Default, Serialize, Deserialize)]
141pub struct TaskOptions {
142    #[serde(default)]
143    pub output: Option<PathBuf>,
144    #[serde(default)]
145    pub connections: Option<usize>,
146    #[serde(default)]
147    pub resume: Option<bool>,
148    #[serde(default)]
149    pub verify: Option<VerifyMode>,
150    #[serde(default)]
151    pub checksum: Option<Checksum>,
152    #[serde(default)]
153    pub extract: Option<bool>,
154    #[serde(default)]
155    pub extract_dir: Option<PathBuf>,
156    #[serde(default)]
157    pub delete_archive: Option<bool>,
158    /// Use the provider cache for Hub tasks (HF-compatible layout for HF).
159    #[serde(default)]
160    pub cache: Option<bool>,
161    #[serde(default)]
162    pub request: RequestOptions,
163    #[serde(default)]
164    pub revision: Option<String>,
165    #[serde(default)]
166    pub include: Vec<String>,
167    #[serde(default)]
168    pub exclude: Vec<String>,
169    #[serde(default)]
170    pub overwrite: bool,
171    #[serde(default)]
172    pub rename_on_conflict: bool,
173    /// Add-time only; persisted for diagnostics.
174    #[serde(default)]
175    pub force: bool,
176}
177
178#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
179#[serde(rename_all = "snake_case")]
180#[non_exhaustive]
181pub enum VerifyMode {
182    #[default]
183    Auto,
184    Require,
185    Disabled,
186}
187
188#[derive(Clone, Debug, Serialize, Deserialize)]
189#[non_exhaustive]
190pub struct FileItem {
191    pub path: String,
192    #[serde(default)]
193    pub url: Option<Url>,
194    #[serde(default)]
195    pub size: Option<u64>,
196    #[serde(default)]
197    pub downloaded: u64,
198    pub state: FileState,
199    #[serde(default)]
200    pub checksum: Option<Checksum>,
201    #[serde(default = "default_selected")]
202    pub selected: bool,
203}
204
205fn default_selected() -> bool {
206    true
207}
208
209#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
210#[serde(rename_all = "snake_case")]
211#[non_exhaustive]
212pub enum FileState {
213    Pending,
214    Downloading,
215    Completed,
216    Skipped,
217    Failed,
218}
219
220#[derive(Clone, Debug, Serialize, Deserialize)]
221#[non_exhaustive]
222pub struct TaskResume {
223    pub version: u32,
224    #[serde(default)]
225    pub files: BTreeMap<String, FileResume>,
226}
227
228impl Default for TaskResume {
229    fn default() -> Self {
230        Self {
231            version: 1,
232            files: BTreeMap::new(),
233        }
234    }
235}
236
237impl TaskResume {
238    pub fn file(&self, url: &str) -> Option<&FileResume> {
239        self.files.get(url)
240    }
241
242    pub fn upsert(&mut self, url: String, file: FileResume) {
243        self.files.insert(url, file);
244    }
245
246    pub fn downloaded(&self) -> u64 {
247        self.files
248            .values()
249            .map(|file| completed_bytes(&file.completed))
250            .sum()
251    }
252}
253
254#[derive(Clone, Debug, Serialize, Deserialize)]
255pub struct FileResume {
256    pub url: String,
257    /// Relative to the task destination, using `/` separators.
258    pub final_path: String,
259    /// Relative to the task destination, using `/` separators.
260    pub part_path: String,
261    #[serde(default)]
262    pub validator: Validator,
263    #[serde(default)]
264    pub total_size: Option<u64>,
265    pub segment_size: u64,
266    #[serde(default)]
267    pub completed: Vec<ByteRange>,
268    #[serde(default)]
269    pub checksum: Option<Checksum>,
270    #[serde(default)]
271    pub metadata: BTreeMap<String, String>,
272    pub updated_at_ms: u64,
273}
274
275impl FileResume {
276    pub fn completed_bytes(&self) -> u64 {
277        completed_bytes(&self.completed)
278    }
279
280    pub fn is_complete(&self) -> bool {
281        match self.total_size {
282            Some(total) => self.completed_bytes() >= total,
283            None => false,
284        }
285    }
286
287    pub fn normalize(&mut self) {
288        self.completed = merge_ranges(std::mem::take(&mut self.completed));
289        self.updated_at_ms = now_ms();
290    }
291}
292
293#[derive(Clone, Debug, Default, Serialize, Deserialize)]
294pub struct Validator {
295    #[serde(default)]
296    pub etag: Option<String>,
297    #[serde(default)]
298    pub last_modified: Option<String>,
299    #[serde(default)]
300    pub size: Option<u64>,
301}
302
303impl Validator {
304    pub fn is_empty(&self) -> bool {
305        self.etag.is_none() && self.last_modified.is_none() && self.size.is_none()
306    }
307
308    /// A stored validator is compatible with a fresh probe when the strongest
309    /// available signal still matches. Weak ETags are not used for range
310    /// validation, so they fall back to Last-Modified + size.
311    pub fn matches(&self, fresh: &Validator) -> bool {
312        if let Some(etag) = &self.etag
313            && !etag.starts_with("W/")
314        {
315            return fresh.etag.as_deref() == Some(etag.as_str());
316        }
317        if let Some(last_modified) = &self.last_modified {
318            return fresh.last_modified.as_deref() == Some(last_modified.as_str())
319                && (self.size.is_none() || self.size == fresh.size);
320        }
321        if let Some(size) = self.size {
322            return fresh.size == Some(size);
323        }
324        false
325    }
326}
327
328pub fn destination_file(destination: &Path, relative: &str) -> PathBuf {
329    destination.join(relative.replace('/', std::path::MAIN_SEPARATOR_STR))
330}
331
332/// Partial-file path used by segmented backends.
333pub fn part_path(final_path: &Path) -> PathBuf {
334    let mut value = final_path.as_os_str().to_os_string();
335    value.push(".shaul.part");
336    PathBuf::from(value)
337}