rusty_cat/
download_trait.rs

1use crate::{InnerErrorCode, MeowError, TransferTask};
2use reqwest::header::HeaderMap;
3
4/// Header merge context for download HEAD request.
5pub struct DownloadHeadCtx<'a> {
6    /// Immutable task snapshot.
7    pub task: &'a TransferTask,
8    /// Mutable base headers cloned from task.
9    pub base: &'a mut HeaderMap,
10}
11
12/// Header merge context for download range GET request.
13pub struct DownloadRangeGetCtx<'a> {
14    /// Immutable task snapshot.
15    pub task: &'a TransferTask,
16    /// Fully formatted `Range` header value, for example `bytes=0-1048575`.
17    pub range_value: &'a str,
18    /// Mutable base headers cloned from task.
19    pub base: &'a mut HeaderMap,
20}
21
22/// Custom breakpoint download protocol.
23///
24/// Implementors control HEAD/range-GET URL and header semantics, and parse
25/// remote total size from HEAD response headers. Executor handles HTTP sending,
26/// response validation, file writes, retries, progress, pause/resume, and state.
27///
28/// # Typical call flow
29///
30/// 1. Prepare stage: executor sends HEAD after `head_url` and
31///    `merge_head_headers`.
32/// 2. Chunk stage: executor sends range GET after `merge_range_get_headers`.
33///
34/// # Executor integration contract
35///
36/// - Default implementation uses task-level `range_accept` as `Accept` header.
37/// - `range_value` is generated by executor and should usually be preserved.
38/// - `total_size_from_head` failure terminates prepare stage.
39///
40/// # Examples
41///
42/// ```no_run
43/// use rusty_cat::api::{
44///     BreakpointDownload, DownloadHeadCtx, DownloadRangeGetCtx, MeowError, StandardRangeDownload,
45/// };
46///
47/// #[derive(Default)]
48/// struct MyDownloadProtocol;
49///
50/// impl BreakpointDownload for MyDownloadProtocol {
51///     fn merge_head_headers(&self, _ctx: DownloadHeadCtx<'_>) -> Result<(), MeowError> {
52///         Ok(())
53///     }
54///
55///     fn merge_range_get_headers(&self, ctx: DownloadRangeGetCtx<'_>) -> Result<(), MeowError> {
56///         // Reuse default behavior or customize as needed.
57///         StandardRangeDownload.merge_range_get_headers(ctx)
58///     }
59/// }
60/// ```
61pub trait BreakpointDownload: Send + Sync {
62    /// Returns full URL for HEAD request.
63    ///
64    /// Default implementation returns [`TransferTask::url`].
65    ///
66    /// # Panics
67    ///
68    /// Implementations should avoid panicking and prefer returning recoverable
69    /// errors from later merge/parse methods.
70    ///
71    /// # Examples
72    ///
73    /// ```no_run
74    /// use rusty_cat::api::{BreakpointDownload, StandardRangeDownload, TransferTask};
75    ///
76    /// fn head_url_for(task: &TransferTask) -> String {
77    ///     BreakpointDownload::head_url(&StandardRangeDownload, task)
78    /// }
79    /// ```
80    fn head_url(&self, task: &TransferTask) -> String {
81        task.url().to_string()
82    }
83
84    /// Merges protocol-specific headers before sending HEAD request.
85    ///
86    /// Default implementation is no-op.
87    ///
88    /// # Errors
89    ///
90    /// Return [`MeowError`] when required HEAD headers cannot be generated
91    /// (for example, signing failure or invalid header values).
92    ///
93    /// # Examples
94    ///
95    /// ```no_run
96    /// use rusty_cat::api::DownloadHeadCtx;
97    ///
98    /// fn inspect_head_ctx(ctx: &DownloadHeadCtx<'_>) {
99    ///     let _ = ctx.task.file_name();
100    ///     let _ = ctx.base.len();
101    /// }
102    /// ```
103    fn merge_head_headers(&self, _ctx: DownloadHeadCtx<'_>) -> Result<(), MeowError> {
104        Ok(())
105    }
106
107    /// Merges protocol-specific headers before range GET request.
108    ///
109    /// Default implementation sets:
110    /// - `Range: <range_value>`
111    /// - `Accept: <task.range_accept or application/octet-stream>`
112    ///
113    /// # Errors
114    ///
115    /// Return [`MeowError`] when protocol-specific range headers cannot be
116    /// generated.
117    ///
118    /// # Examples
119    ///
120    /// ```no_run
121    /// use rusty_cat::api::DownloadRangeGetCtx;
122    ///
123    /// fn inspect_range_ctx(ctx: &DownloadRangeGetCtx<'_>) {
124    ///     let _ = (ctx.range_value, ctx.task.url());
125    /// }
126    /// ```
127    fn merge_range_get_headers(&self, ctx: DownloadRangeGetCtx<'_>) -> Result<(), MeowError> {
128        let _ = self;
129        crate::http_breakpoint::insert_header(ctx.base, "Range", ctx.range_value);
130        let accept = ctx
131            .task
132            .breakpoint_download_http()
133            .map(|c| c.range_accept.as_str())
134            .unwrap_or(crate::http_breakpoint::DEFAULT_RANGE_ACCEPT);
135        crate::http_breakpoint::insert_header(ctx.base, "Accept", accept);
136        Ok(())
137    }
138
139    /// Parses total resource size from successful HEAD response headers.
140    ///
141    /// Default implementation requires valid `Content-Length > 0`.
142    ///
143    /// # Errors
144    ///
145    /// Returns `MissingOrInvalidContentLengthFromHead` when total size cannot
146    /// be parsed from response headers.
147    ///
148    /// # Examples
149    ///
150    /// ```no_run
151    /// use reqwest::header::{HeaderMap, HeaderValue, CONTENT_LENGTH};
152    /// use rusty_cat::api::{BreakpointDownload, StandardRangeDownload};
153    ///
154    /// let mut headers = HeaderMap::new();
155    /// headers.insert(CONTENT_LENGTH, HeaderValue::from_static("1024"));
156    /// let total = StandardRangeDownload.total_size_from_head(&headers)?;
157    /// assert_eq!(total, 1024);
158    /// # Ok::<(), rusty_cat::api::MeowError>(())
159    /// ```
160    fn total_size_from_head(&self, headers: &HeaderMap) -> Result<u64, MeowError> {
161        headers
162            .get(reqwest::header::CONTENT_LENGTH)
163            .and_then(|v| v.to_str().ok())
164            .and_then(|s| s.parse::<u64>().ok())
165            .filter(|&n| n > 0)
166            .ok_or_else(|| {
167                MeowError::from_code_str(
168                    InnerErrorCode::MissingOrInvalidContentLengthFromHead,
169                    "missing or invalid content-length from HEAD",
170                )
171            })
172    }
173}
rusty_cat/download_trait.rs

rusty_cat/
download_trait.rs
