rusty-cat 0.2.2

Async HTTP client for resumable file upload and download.
Documentation 
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

use async_trait::async_trait;

use crate::chunk_outcome::ChunkOutcome;
use crate::error::MeowError;
use crate::prepare_outcome::PrepareOutcome;
use crate::transfer_task::TransferTask;

/// Low-level transfer executor abstraction used by scheduler/runtime.
///
/// Most users do not implement this trait directly unless they are building a
/// custom transport backend.
///
/// # Examples
///
/// ```no_run
/// use async_trait::async_trait;
/// use rusty_cat::api::{ChunkOutcome, MeowError, PrepareOutcome, TransferTask, TransferTrait};
///
/// struct NoopExecutor;
///
/// #[async_trait]
/// impl TransferTrait for NoopExecutor {
///     async fn prepare(
///         &self,
///         _task: &TransferTask,
///         local_offset: u64,
///     ) -> Result<PrepareOutcome, MeowError> {
///         Ok(PrepareOutcome { next_offset: local_offset, total_size: local_offset })
///     }
///
///     async fn transfer_chunk(
///         &self,
///         _task: &TransferTask,
///         offset: u64,
///         _chunk_size: u64,
///         remote_total_size: u64,
///     ) -> Result<ChunkOutcome, MeowError> {
///         Ok(ChunkOutcome {
///             next_offset: offset,
///             total_size: remote_total_size,
///             done: true,
///             completion_payload: None,
///         })
///     }
/// }
/// ```
#[async_trait]
pub trait TransferTrait: Send + Sync {
    /// Prepares transfer state and computes the next offset to run.
    ///
    /// # Parameters
    ///
    /// - `task`: Immutable task snapshot.
    /// - `local_offset`: Current local persisted offset, in bytes.
    ///
    /// # Returns
    ///
    /// Returns [`PrepareOutcome`] containing next offset and total size.
    ///
    /// # Errors
    ///
    /// Return [`MeowError`] when checkpoint probing, local/remote validation,
    /// or protocol initialization fails.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use rusty_cat::api::TransferTask;
    ///
    /// fn inspect_prepare_input(task: &TransferTask, local_offset: u64) {
    ///     let _ = (task.url(), local_offset);
    /// }
    /// ```
    async fn prepare(
        &self,
        task: &TransferTask,
        local_offset: u64,
    ) -> Result<PrepareOutcome, MeowError>;

    /// Transfers one chunk from the given offset.
    ///
    /// # Parameters
    ///
    /// - `offset`: Start byte offset for this chunk.
    /// - `chunk_size`: Desired chunk size in bytes (`>= 1` recommended).
    /// - `remote_total_size`: For download, use `prepare.total_size`; for
    ///   upload, usually equals `task.total_size()`.
    ///
    /// # Errors
    ///
    /// Return [`MeowError`] when chunk transfer fails, range validation fails,
    /// or local file I/O fails.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use rusty_cat::api::TransferTask;
    ///
    /// fn inspect_chunk_input(task: &TransferTask, offset: u64, chunk_size: u64, remote_total_size: u64) {
    ///     let _ = (task.file_name(), offset, chunk_size, remote_total_size);
    /// }
    /// ```
    async fn transfer_chunk(
        &self,
        task: &TransferTask,
        offset: u64,
        chunk_size: u64,
        remote_total_size: u64,
    ) -> Result<ChunkOutcome, MeowError>;

    /// Handles protocol-specific cancel semantics.
    ///
    /// Default implementation is a no-op.
    ///
    /// # Errors
    ///
    /// Implementations should return [`MeowError`] if remote abort/cancel
    /// actions fail.
    async fn cancel(&self, _task: &TransferTask) -> Result<(), MeowError> {
        Ok(())
    }
}