Trait BreakpointDownload 

pub trait BreakpointDownload: Send + Sync {
    // Provided methods
    fn total_size_hint(&self, _task: &TransferTask) -> Option<u64> { ... }
    fn head_url(&self, task: &TransferTask) -> String { ... }
    fn range_url(&self, task: &TransferTask) -> String { ... }
    fn merge_head_headers(
        &self,
        _ctx: DownloadHeadCtx<'_>,
    ) -> Result<(), MeowError> { ... }
    fn merge_range_get_headers(
        &self,
        ctx: DownloadRangeGetCtx<'_>,
    ) -> Result<(), MeowError> { ... }
    fn total_size_from_head(
        &self,
        headers: &HeaderMap,
    ) -> Result<u64, MeowError> { ... }
}

Custom breakpoint download protocol.

Implementors control HEAD/range-GET URL and header semantics, and parse remote total size from HEAD response headers. Executor handles HTTP sending, response validation, file writes, retries, progress, pause/resume, and state.

Typical call flow

1. Prepare stage: executor sends HEAD after head_url and merge_head_headers.
2. Chunk stage: executor sends range GET after merge_range_get_headers.

Executor integration contract

• Default implementation uses task-level range_accept as Accept header.
• range_value is generated by executor and should usually be preserved.
• total_size_from_head failure terminates prepare stage.

Examples

use rusty_cat::api::{
    BreakpointDownload, DownloadHeadCtx, DownloadRangeGetCtx, MeowError, StandardRangeDownload,
};

#[derive(Default)]
struct MyDownloadProtocol;

impl BreakpointDownload for MyDownloadProtocol {
    fn merge_head_headers(&self, _ctx: DownloadHeadCtx<'_>) -> Result<(), MeowError> {
        Ok(())
    }

    fn merge_range_get_headers(&self, ctx: DownloadRangeGetCtx<'_>) -> Result<(), MeowError> {
        // Reuse default behavior or customize as needed.
        StandardRangeDownload.merge_range_get_headers(ctx)
    }
}

Provided Methods

fn total_size_hint(&self, _task: &TransferTask) -> Option<u64>

Returns known remote total size and skips the HEAD prepare request when present.

This is useful for presigned URL downloads where a GET URL cannot be reused as HEAD, or where the application server already returned object metadata together with the presigned range URL.

fn head_url(&self, task: &TransferTask) -> String

Returns full URL for HEAD request.

Default implementation returns TransferTask::url.

Panics

Implementations should avoid panicking and prefer returning recoverable errors from later merge/parse methods.

Examples

use rusty_cat::api::{BreakpointDownload, StandardRangeDownload, TransferTask};

fn head_url_for(task: &TransferTask) -> String {
    BreakpointDownload::head_url(&StandardRangeDownload, task)
}

fn range_url(&self, task: &TransferTask) -> String

Returns full URL for range GET requests.

Default implementation returns TransferTask::url. Presigned protocols can override this when HEAD and GET use different URLs.

fn merge_head_headers(&self, _ctx: DownloadHeadCtx<'_>) -> Result<(), MeowError>

Merges protocol-specific headers before sending HEAD request.

Default implementation is no-op.

Errors

Return MeowError when required HEAD headers cannot be generated (for example, signing failure or invalid header values).

Examples

use rusty_cat::api::DownloadHeadCtx;

fn inspect_head_ctx(ctx: &DownloadHeadCtx<'_>) {
    let _ = ctx.task.file_name();
    let _ = ctx.base.len();
}

fn merge_range_get_headers( &self, ctx: DownloadRangeGetCtx<'_>, ) -> Result<(), MeowError>

Merges protocol-specific headers before range GET request.

Default implementation sets:

• Range: <range_value>
• Accept: <task.range_accept or application/octet-stream>

Errors

Return MeowError when protocol-specific range headers cannot be generated.

Examples

use rusty_cat::api::DownloadRangeGetCtx;

fn inspect_range_ctx(ctx: &DownloadRangeGetCtx<'_>) {
    let _ = (ctx.range_value, ctx.task.url());
}

fn total_size_from_head(&self, headers: &HeaderMap) -> Result<u64, MeowError>

Parses total resource size from successful HEAD response headers.

Default implementation requires valid Content-Length > 0.

Errors

Returns MissingOrInvalidContentLengthFromHead when total size cannot be parsed from response headers.

Examples

use reqwest::header::{HeaderMap, HeaderValue, CONTENT_LENGTH};
use rusty_cat::api::{BreakpointDownload, StandardRangeDownload};

let mut headers = HeaderMap::new();
headers.insert(CONTENT_LENGTH, HeaderValue::from_static("1024"));
let total = StandardRangeDownload.total_size_from_head(&headers)?;
assert_eq!(total, 1024);

Implementors

impl BreakpointDownload for StandardRangeDownload