1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
use crate::direction::Direction;
use crate::http_breakpoint::{BreakpointDownload, BreakpointDownloadHttpConfig};
use crate::pounce_task::PounceTask;
use reqwest::header::HeaderMap;
use reqwest::Method;
use std::path::{Path, PathBuf};
use std::sync::Arc;
/// Builder for creating a download [`PounceTask`].
///
/// Use this builder when you need fine-grained control over URL, headers,
/// and breakpoint download behavior.
///
/// # HTTP method
///
/// Download HTTP methods are **not configurable**: the executor always issues
/// `HEAD` during the prepare stage and `GET` with `Range` headers during
/// chunk transfer. These are fixed by the HTTP Range protocol (RFC 7233) and
/// by the breakpoint-resume contract, so there is no builder knob for the
/// request method. If a gateway requires an unusual verb, implement a custom
/// [`BreakpointDownload`] instead.
pub struct DownloadPounceBuilder {
/// Display file name used in callbacks and logs.
file_name: String,
/// Target local file path.
file_path: PathBuf,
/// Chunk size in bytes for each range request.
///
/// Effective range: `>= 1`; zero is normalized to default (1 MiB).
chunk_size: u64,
/// Resource URL.
url: String,
/// Base headers copied into HEAD and range GET requests.
headers: HeaderMap,
/// Optional client-defined file signature shown in progress records.
client_file_sign: Option<String>,
/// Optional custom breakpoint download protocol implementation.
breakpoint_download: Option<Arc<dyn BreakpointDownload + Send + Sync>>,
/// Optional per-task HTTP behavior for range download.
breakpoint_download_http: Option<BreakpointDownloadHttpConfig>,
/// Maximum retry count per chunk transfer.
///
/// Effective range: `>= 0`; `0` means "do not retry".
max_chunk_retries: u32,
}
impl DownloadPounceBuilder {
/// Creates a new download task builder.
///
/// # Parameters
///
/// - `file_name`: Non-empty display name for logs/callbacks.
/// - `file_path`: Local output path.
/// - `chunk_size`: Desired chunk size in bytes; `0` falls back to default.
/// - `url`: Download URL.
///
/// The HTTP method is fixed by protocol (`HEAD` for prepare, `GET` with
/// `Range` for chunks) and is therefore not a parameter; see the
/// [struct-level docs](DownloadPounceBuilder) for details.
///
/// # Usage rules
///
/// Duplicate task detection is based on direction + URL in scheduler logic.
///
/// # Examples
///
/// ```no_run
/// use rusty_cat::api::DownloadPounceBuilder;
///
/// let task = DownloadPounceBuilder::new(
/// "demo.bin",
/// "./downloads/demo.bin",
/// 1024 * 1024,
/// "https://example.com/demo.bin",
/// )
/// .build();
/// let _ = task;
/// ```
pub fn new(
file_name: impl Into<String>,
file_path: impl AsRef<Path>,
chunk_size: u64,
url: impl Into<String>,
) -> Self {
Self {
file_name: file_name.into(),
file_path: file_path.as_ref().to_path_buf(),
chunk_size: PounceTask::normalized_chunk_size(chunk_size),
url: url.into(),
headers: HeaderMap::new(),
client_file_sign: None,
breakpoint_download: None,
breakpoint_download_http: None,
max_chunk_retries: PounceTask::DEFAULT_MAX_CHUNK_RETRIES,
}
}
/// Overrides the request URL.
///
/// # Examples
///
/// ```no_run
/// use rusty_cat::api::DownloadPounceBuilder;
///
/// let _task = DownloadPounceBuilder::new("a.bin", "./a.bin", 1024, "https://old")
/// .with_url("https://new")
/// .build();
/// ```
pub fn with_url(mut self, url: impl Into<String>) -> Self {
self.url = url.into();
self
}
/// Overrides target local file path.
///
/// # Examples
///
/// ```no_run
/// use rusty_cat::api::DownloadPounceBuilder;
///
/// let _task = DownloadPounceBuilder::new("a.bin", "./a.bin", 1024, "https://x")
/// .with_file_path("./downloads/new-a.bin")
/// .build();
/// ```
pub fn with_file_path(mut self, path: impl AsRef<Path>) -> Self {
self.file_path = path.as_ref().to_path_buf();
self
}
/// Replaces base request headers.
///
/// Provide authorization and other business headers here.
///
/// # Examples
///
/// ```no_run
/// use reqwest::header::{HeaderMap, HeaderValue, AUTHORIZATION};
/// use rusty_cat::api::DownloadPounceBuilder;
///
/// let mut headers = HeaderMap::new();
/// headers.insert(AUTHORIZATION, HeaderValue::from_static("Bearer token"));
///
/// let _task = DownloadPounceBuilder::new("a.bin", "./a.bin", 1024, "https://x")
/// .with_headers(headers)
/// .build();
/// ```
pub fn with_headers(mut self, headers: HeaderMap) -> Self {
self.headers = headers;
self
}
/// Sets optional client-side file signature for progress reporting.
///
/// # Examples
///
/// ```no_run
/// use rusty_cat::api::DownloadPounceBuilder;
///
/// let _task = DownloadPounceBuilder::new("a.bin", "./a.bin", 1024, "https://x")
/// .with_client_file_sign("client-sign-001")
/// .build();
/// ```
pub fn with_client_file_sign(mut self, sign: impl Into<String>) -> Self {
self.client_file_sign = Some(sign.into());
self
}
/// Sets a custom breakpoint download implementation for this task only.
///
/// # Examples
///
/// ```no_run
/// use std::sync::Arc;
/// use rusty_cat::api::{DownloadPounceBuilder, StandardRangeDownload};
///
/// let protocol = Arc::new(StandardRangeDownload);
/// let _task = DownloadPounceBuilder::new("a.bin", "./a.bin", 1024, "https://x")
/// .with_breakpoint_download(protocol)
/// .build();
/// ```
pub fn with_breakpoint_download(
mut self,
download: Arc<dyn BreakpointDownload + Send + Sync>,
) -> Self {
self.breakpoint_download = Some(download);
self
}
/// Sets HTTP behavior config for breakpoint range download.
///
/// # Examples
///
/// ```no_run
/// use rusty_cat::api::{BreakpointDownloadHttpConfig, DownloadPounceBuilder};
///
/// let _task = DownloadPounceBuilder::new("a.bin", "./a.bin", 1024, "https://x")
/// .with_breakpoint_download_http(BreakpointDownloadHttpConfig {
/// range_accept: "application/octet-stream".to_string(),
/// })
/// .build();
/// ```
pub fn with_breakpoint_download_http(mut self, config: BreakpointDownloadHttpConfig) -> Self {
self.breakpoint_download_http = Some(config);
self
}
/// Configures max retry attempts per chunk (default: `3`).
///
/// # Range guidance
///
/// - `0`: no retry.
/// - `1..=10`: common production range.
///
/// # Examples
///
/// ```no_run
/// use rusty_cat::api::DownloadPounceBuilder;
///
/// let _task = DownloadPounceBuilder::new("a.bin", "./a.bin", 1024, "https://x")
/// .with_max_chunk_retries(5)
/// .build();
/// ```
pub fn with_max_chunk_retries(mut self, retries: u32) -> Self {
self.max_chunk_retries = PounceTask::normalized_max_chunk_retries(retries);
self
}
/// Builds the final download [`PounceTask`].
///
/// This operation is infallible; validation occurs during enqueue/runtime.
///
/// # Examples
///
/// ```no_run
/// use rusty_cat::api::DownloadPounceBuilder;
///
/// let task = DownloadPounceBuilder::new(
/// "file.iso",
/// "./downloads/file.iso",
/// 2 * 1024 * 1024,
/// "https://example.com/file.iso",
/// )
/// .build();
/// let _ = task;
/// ```
pub fn build(self) -> PounceTask {
PounceTask {
direction: Direction::Download,
file_name: self.file_name,
file_path: self.file_path,
upload_source: None,
total_size: 0,
chunk_size: self.chunk_size,
url: self.url,
// Download uses HEAD (prepare) + GET (chunks) hard-coded by the
// executor; this field is a placeholder and is never consulted on
// the download path.
method: Method::GET,
headers: self.headers,
client_file_sign: self.client_file_sign,
breakpoint_upload: None,
breakpoint_download: self.breakpoint_download,
breakpoint_download_http: self.breakpoint_download_http,
max_chunk_retries: self.max_chunk_retries,
max_upload_prepare_retries: PounceTask::DEFAULT_MAX_UPLOAD_PREPARE_RETRIES,
}
}
}