reqwest_drive/
lib.rs

1#[cfg(doctest)]
2doc_comment::doctest!("../README.md");
3
4use std::path::Path;
5
6pub use reqwest_middleware::{ClientBuilder, ClientWithMiddleware};
7
8mod cache_middleware;
9pub use cache_middleware::{CachePolicy, DriveCache};
10
11mod throttle_middleware;
12pub use throttle_middleware::{DriveThrottleBackoff, ThrottlePolicy};
13
14use simd_r_drive::DataStore;
15use std::sync::Arc;
16
17// TODO: Add usage examples here
18
19/// Initializes only the cache middleware with a file-based data store.
20///
21/// This function creates a new `DriveCache` instance backed by a `DataStore` file.
22///
23/// # Arguments
24///
25/// * `cache_storage_file` - Path to the file where cached responses are stored.
26/// * `policy` - The cache expiration policy.
27///
28/// # Returns
29///
30/// An `Arc<DriveCache>` instance managing the cache.
31pub fn init_cache(cache_storage_file: &Path, policy: CachePolicy) -> Arc<DriveCache> {
32    Arc::new(DriveCache::new(cache_storage_file, policy))
33}
34
35/// Initializes both cache and throttle middleware with a file-based data store.
36///
37/// This function creates:
38/// - A `DriveCache` instance for response caching.
39/// - A `DriveThrottleBackoff` instance for rate-limiting and retrying failed requests.
40///
41/// # Arguments
42///
43/// * `cache_storage_file` - Path to the file where cached responses are stored.
44/// * `cache_policy` - The cache expiration policy.
45/// * `throttle_policy` - The throttling and backoff policy.
46///
47/// # Returns
48///
49/// A tuple containing:
50/// - `Arc<DriveCache>` for caching.
51/// - `Arc<DriveThrottleBackoff>` for throttling.
52pub fn init_cache_with_throttle(
53    cache_storage_file: &Path,
54    cache_policy: CachePolicy,
55    throttle_policy: ThrottlePolicy,
56) -> (Arc<DriveCache>, Arc<DriveThrottleBackoff>) {
57    let cache = Arc::new(DriveCache::new(cache_storage_file, cache_policy));
58    let throttle = Arc::new(DriveThrottleBackoff::new(
59        throttle_policy,
60        Arc::clone(&cache),
61    ));
62    (cache, throttle)
63}
64
65/// Initializes only the cache middleware using an **existing** `Arc<DataStore>`.
66///
67/// This function is useful if a shared `DataStore` instance already exists
68/// and should be reused instead of creating a new one.
69///
70/// # Arguments
71///
72/// * `store` - A shared `Arc<DataStore>` instance.
73/// * `policy` - The cache expiration policy.
74///
75/// # Returns
76///
77/// An `Arc<DriveCache>` instance managing the cache.
78pub fn init_cache_with_drive(store: Arc<DataStore>, policy: CachePolicy) -> Arc<DriveCache> {
79    Arc::new(DriveCache::with_drive_arc(store, policy))
80}
81
82/// Initializes both cache and throttle middleware using an **existing** `Arc<DataStore>`.
83///
84/// This function is useful if a shared `DataStore` instance already exists
85/// and should be reused instead of creating a new one.
86///
87/// # Arguments
88///
89/// * `store` - A shared `Arc<DataStore>` instance.
90/// * `cache_policy` - The cache expiration policy.
91/// * `throttle_policy` - The throttling and backoff policy.
92///
93/// # Returns
94///
95/// A tuple containing:
96/// - `Arc<DriveCache>` for caching.
97/// - `Arc<DriveThrottleBackoff>` for throttling.
98pub fn init_cache_with_drive_and_throttle(
99    store: Arc<DataStore>,
100    cache_policy: CachePolicy,
101    throttle_policy: ThrottlePolicy,
102) -> (Arc<DriveCache>, Arc<DriveThrottleBackoff>) {
103    let cache = Arc::new(DriveCache::with_drive_arc(store, cache_policy));
104    let throttle = Arc::new(DriveThrottleBackoff::new(
105        throttle_policy,
106        Arc::clone(&cache),
107    ));
108    (cache, throttle)
109}
110
111/// Initializes a `reqwest` client with both cache and throttle middleware.
112///
113/// This function constructs a `ClientWithMiddleware` by attaching:
114/// - A `DriveCache` instance for caching HTTP responses.
115/// - A `DriveThrottleBackoff` instance for request throttling and backoff handling.
116///
117/// ## Arguments
118///
119/// * `cache` - A shared `Arc<DriveCache>` instance for caching responses.
120/// * `throttle` - A shared `Arc<DriveThrottleBackoff>` instance for throttling requests.
121///
122/// ## Returns
123///
124/// A `ClientWithMiddleware` instance that includes both caching and throttling.
125///
126/// ## Example
127///
128/// ```rust
129/// use reqwest_drive::{init_cache_with_throttle, init_client_with_cache_and_throttle, CachePolicy, ThrottlePolicy};
130/// use reqwest_middleware::ClientWithMiddleware;
131/// use std::path::Path;
132/// use std::sync::Arc;
133/// use std::time::Duration;
134///
135/// #[tokio::main]
136/// async fn main() {
137///     let cache_policy = CachePolicy {
138///         default_ttl: Duration::from_secs(60),
139///         respect_headers: true,
140///         cache_status_override: None,
141///     };
142///
143///     let throttle_policy = ThrottlePolicy {
144///         base_delay_ms: 200,
145///         adaptive_jitter_ms: 100,
146///         max_concurrent: 2,
147///         max_retries: 2,
148///     };
149///
150///     let (cache, throttle) = init_cache_with_throttle(Path::new("cache_storage.bin"), cache_policy, throttle_policy);
151///
152///     let client: ClientWithMiddleware = init_client_with_cache_and_throttle(cache, throttle);
153///
154///     let response = client.get("https://httpbin.org/get").send().await.unwrap();
155///
156///     assert!(response.status().is_success());
157/// }
158/// ```
159pub fn init_client_with_cache_and_throttle(
160    cache: Arc<DriveCache>,
161    throttle: Arc<DriveThrottleBackoff>,
162) -> ClientWithMiddleware {
163    ClientBuilder::new(reqwest::Client::new())
164        .with_arc(cache)
165        .with_arc(throttle)
166        .build()
167}
reqwest_drive/lib.rs

reqwest_drive/
lib.rs
