Skip to main content

quai_rpc/fetch/
client.rs

1use super::*;
2use std::{
3    future::Future,
4    sync::{Arc, Mutex},
5    task::{Poll, Waker},
6};
7/// Native implementations support multithreaded executors.
8#[cfg(not(target_arch = "wasm32"))]
9pub trait FetchThreading: Send + Sync {}
10#[cfg(not(target_arch = "wasm32"))]
11impl<T: Send + Sync> FetchThreading for T {}
12/// Browser implementations may own thread-local JavaScript handles.
13#[cfg(target_arch = "wasm32")]
14pub trait FetchThreading {}
15#[cfg(target_arch = "wasm32")]
16impl<T> FetchThreading for T {}
17/// Native resource futures are Send.
18#[cfg(not(target_arch = "wasm32"))]
19pub trait FetchFuture: Future + Send {}
20#[cfg(not(target_arch = "wasm32"))]
21impl<T: Future + Send> FetchFuture for T {}
22/// Browser resource futures do not require Send.
23#[cfg(target_arch = "wasm32")]
24pub trait FetchFuture: Future {}
25#[cfg(target_arch = "wasm32")]
26impl<T: Future> FetchFuture for T {}
27/// Runtime adapter. Execute must make exactly one HTTP request without redirects
28/// or retries, bound wire and decoded bodies, and cancel active I/O on future drop.
29pub trait FetchBackend: FetchThreading {
30    /// Monotonic milliseconds, finite and nonnegative.
31    fn now(&self) -> Result<f64, FetchError>;
32    /// An owned cancellable delay. Dropping the future must release timers.
33    fn sleep(&self, milliseconds: u32) -> impl FetchFuture<Output = Result<(), FetchError>>;
34    /// One HTTP(S) exchange. Non-success statuses are returned as response data.
35    fn execute(
36        &self,
37        request: &FetchRequest,
38        max_bytes: usize,
39    ) -> impl FetchFuture<Output = Result<FetchResponse, FetchError>>;
40}
41/// Explicit processing result; retry is a decision, not a special thrown error.
42pub enum FetchAction {
43    /// Return this response to the caller.
44    Return(FetchResponse),
45    /// Request a bounded retry after this delay (subject to method and attempt policy).
46    Retry {
47        /// Response available to the retry hook or final caller.
48        response: FetchResponse,
49        /// Delay in milliseconds, at most the overall timeout.
50        delay_ms: u32,
51    },
52}
53/// A custom scheme resolves either to an HTTP request or an immediate response.
54pub enum FetchGateway {
55    /// Continue with exactly one HTTP(S) exchange.
56    Request(FetchRequest),
57    /// Return a locally resolved resource through the process hook.
58    Response(FetchResponse),
59}
60/// Per-client immutable hook implementation; applications can hold their own
61/// registry or middleware state. No mutable process-global registry is installed.
62pub trait FetchHooks: FetchThreading {
63    /// Resolve custom schemes. HTTP(S) cannot be replaced through a gateway hook.
64    fn gateway(
65        &self,
66        _request: &FetchRequest,
67    ) -> impl FetchFuture<Output = Result<Option<FetchGateway>, FetchError>> {
68        async { Ok(None) }
69    }
70    /// Update headers/body before each actual exchange. Result is revalidated.
71    fn preflight(
72        &self,
73        request: &FetchRequest,
74    ) -> impl FetchFuture<Output = Result<FetchRequest, FetchError>> {
75        async { Ok(request.clone()) }
76    }
77    /// Transform response or explicitly ask for a retry.
78    fn process(
79        &self,
80        _request: &FetchRequest,
81        response: FetchResponse,
82    ) -> impl FetchFuture<Output = Result<FetchAction, FetchError>> {
83        async { Ok(FetchAction::Return(response)) }
84    }
85    /// Permit/reject each proposed retry; attempt is the completed exchange count.
86    fn retry(
87        &self,
88        _request: &FetchRequest,
89        _response: &FetchResponse,
90        _attempt: u32,
91    ) -> impl FetchFuture<Output = Result<bool, FetchError>> {
92        async { Ok(true) }
93    }
94}
95/// Default hooks preserve all requests and responses.
96#[derive(Clone, Copy, Debug, Default)]
97pub struct NoFetchHooks;
98impl FetchHooks for NoFetchHooks {}
99/// Independent resource policy; none of these settings change RPC transport behavior.
100#[derive(Clone, Copy, Debug)]
101#[non_exhaustive]
102pub struct FetchConfig {
103    /// Overall timeout including hooks and delays, 1..=i32::MAX milliseconds.
104    pub timeout_ms: u32,
105    /// Maximum wire and decoded response bytes, 1..=1 MiB.
106    pub max_response_bytes: usize,
107    /// Maximum exchanges, including redirects/retries, 1..=12. Default one.
108    pub max_attempts: u32,
109    /// Maximum redirects, 0..=10. Default zero; only GET/HEAD may redirect.
110    pub max_redirects: u32,
111    /// Base deterministic exponential delay for 429, capped by the deadline.
112    pub retry_delay_ms: u32,
113    /// Explicit permission to retry methods other than GET/HEAD. Defaults false.
114    pub retry_non_idempotent: bool,
115}
116impl FetchConfig {
117    /// Replace `timeout_ms`.
118    pub const fn with_timeout_ms(mut self, timeout_ms: u32) -> Self {
119        self.timeout_ms = timeout_ms;
120        self
121    }
122    /// Replace `max_response_bytes`.
123    pub const fn with_max_response_bytes(mut self, max_response_bytes: usize) -> Self {
124        self.max_response_bytes = max_response_bytes;
125        self
126    }
127    /// Replace `max_attempts`.
128    pub const fn with_max_attempts(mut self, max_attempts: u32) -> Self {
129        self.max_attempts = max_attempts;
130        self
131    }
132    /// Replace `max_redirects`.
133    pub const fn with_max_redirects(mut self, max_redirects: u32) -> Self {
134        self.max_redirects = max_redirects;
135        self
136    }
137    /// Replace `retry_delay_ms`.
138    pub const fn with_retry_delay_ms(mut self, retry_delay_ms: u32) -> Self {
139        self.retry_delay_ms = retry_delay_ms;
140        self
141    }
142    /// Replace `retry_non_idempotent`.
143    pub const fn with_retry_non_idempotent(mut self, retry_non_idempotent: bool) -> Self {
144        self.retry_non_idempotent = retry_non_idempotent;
145        self
146    }
147}
148impl Default for FetchConfig {
149    fn default() -> Self {
150        Self {
151            timeout_ms: 10_000,
152            max_response_bytes: MAX_FETCH_BYTES,
153            max_attempts: 1,
154            max_redirects: 0,
155            retry_delay_ms: 250,
156            retry_non_idempotent: false,
157        }
158    }
159}
160impl FetchConfig {
161    /// Check all bounds before hooks, timers or I/O.
162    pub fn validate(self) -> Result<(), FetchError> {
163        if self.timeout_ms == 0
164            || self.timeout_ms > i32::MAX as u32
165            || !(1..=MAX_FETCH_BYTES).contains(&self.max_response_bytes)
166            || !(1..=12).contains(&self.max_attempts)
167            || self.max_redirects > 10
168            || self.retry_delay_ms > self.timeout_ms
169        {
170            return Err(FetchError::Invalid);
171        }
172        Ok(())
173    }
174}
175#[derive(Default)]
176struct CancelState {
177    cancelled: bool,
178    active: bool,
179    waker: Option<Waker>,
180}
181/// Cloneable one-operation cancellation token. Cancel is permanent; a fresh token
182/// is needed for another operation after cancellation. Never logs request data.
183#[derive(Clone, Default)]
184pub struct FetchCancellation(Arc<Mutex<CancelState>>);
185impl FetchCancellation {
186    /// Signal the active operation and wake it promptly. No remote rollback is implied.
187    pub fn cancel(&self) {
188        let wake = {
189            let mut s = self.0.lock().unwrap();
190            s.cancelled = true;
191            s.waker.take()
192        };
193        if let Some(w) = wake {
194            w.wake();
195        }
196    }
197    /// True after cancellation, including before a send begins.
198    pub fn cancelled(&self) -> bool {
199        self.0.lock().unwrap().cancelled
200    }
201    fn begin(&self) -> Result<CancelGuard, FetchError> {
202        let mut s = self.0.lock().unwrap();
203        if s.cancelled {
204            return Err(FetchError::Cancelled);
205        }
206        if s.active {
207            return Err(FetchError::Active);
208        }
209        s.active = true;
210        Ok(CancelGuard(self.clone()))
211    }
212    fn check(&self, waker: &Waker) -> Result<(), FetchError> {
213        let mut s = self.0.lock().unwrap();
214        if s.cancelled {
215            return Err(FetchError::Cancelled);
216        }
217        if !s.waker.as_ref().is_some_and(|w| w.will_wake(waker)) {
218            s.waker = Some(waker.clone());
219        }
220        Ok(())
221    }
222}
223struct CancelGuard(FetchCancellation);
224impl Drop for CancelGuard {
225    fn drop(&mut self) {
226        let mut s = self.0.0.lock().unwrap();
227        s.active = false;
228        s.waker = None;
229    }
230}
231/// Result with explicit original and final request context; Debug stays redacted.
232#[derive(Debug)]
233#[non_exhaustive]
234pub struct FetchedResource {
235    /// Caller-supplied request before hooks/gateways/redirects.
236    pub original: FetchRequest,
237    /// Actual final request (or local resource request).
238    pub request: FetchRequest,
239    /// Exact bounded response after processing.
240    pub response: FetchResponse,
241    /// Number of completed HTTP exchanges (zero for a local data URI).
242    pub attempts: u32,
243}
244/// Owned runtime and hooks with an immutable bounded policy.
245pub struct FetchClient<B, H = NoFetchHooks> {
246    backend: B,
247    hooks: H,
248    config: FetchConfig,
249}
250impl<B: FetchBackend> FetchClient<B> {
251    /// Create a client using identity hooks.
252    pub fn new(backend: B, config: FetchConfig) -> Result<Self, FetchError> {
253        Self::with_hooks(backend, config, NoFetchHooks)
254    }
255}
256impl<B: FetchBackend, H: FetchHooks> FetchClient<B, H> {
257    /// Supply explicit hooks; no global registrations or locks are needed.
258    pub fn with_hooks(backend: B, config: FetchConfig, hooks: H) -> Result<Self, FetchError> {
259        config.validate()?;
260        Ok(Self {
261            backend,
262            hooks,
263            config,
264        })
265    }
266    /// Borrow the fixed policy.
267    pub fn config(&self) -> FetchConfig {
268        self.config
269    }
270    /// Borrow the backend to share connection/runtime state explicitly.
271    pub fn backend(&self) -> &B {
272        &self.backend
273    }
274    /// Fetch under an overall deadline. Dropping this future cancels local I/O,
275    /// hooks and delays; state-changing remote requests may already have executed.
276    /// Transport failures are never automatically retried.
277    pub async fn send(
278        &self,
279        request: &FetchRequest,
280        cancel: &FetchCancellation,
281    ) -> Result<FetchedResource, FetchError> {
282        request.validate()?;
283        let _guard = cancel.begin()?;
284        let start = self.backend.now()?;
285        if !start.is_finite() || start < 0.0 {
286            return Err(FetchError::Transport);
287        }
288        let expired = || {
289            let n = self.backend.now()?;
290            if !n.is_finite() || n < start {
291                return Err(FetchError::Transport);
292            }
293            Ok(n - start >= f64::from(self.config.timeout_ms))
294        };
295        let mut deadline = std::pin::pin!(self.backend.sleep(self.config.timeout_ms));
296        let work = async {
297            let mut req = request.clone();
298            let mut attempts = 0;
299            let mut redirects = 0;
300            loop {
301                let mut response = if !matches!(req.scheme(), "http" | "https") {
302                    let gateway = self.hooks.gateway(&req).await?;
303                    let gateway = match gateway {
304                        Some(g) => g,
305                        None if req.scheme() == "data" => {
306                            FetchGateway::Response(data_resource(req.url())?)
307                        }
308                        _ => return Err(FetchError::Unsupported),
309                    };
310                    match gateway {
311                        FetchGateway::Response(response) => Some(response),
312                        FetchGateway::Request(next) => {
313                            if !matches!(next.scheme(), "http" | "https") {
314                                return Err(FetchError::Unsupported);
315                            }
316                            req = next;
317                            None
318                        }
319                    }
320                } else {
321                    None
322                };
323                if response.is_none() {
324                    req = self.hooks.preflight(&req).await?;
325                    req.validate()?;
326                    if !matches!(req.scheme(), "http" | "https") {
327                        return Err(FetchError::Unsupported);
328                    }
329                    response = Some(
330                        self.backend
331                            .execute(&req, self.config.max_response_bytes)
332                            .await?,
333                    );
334                    attempts += 1;
335                }
336                let response = response.unwrap();
337                if response
338                    .body()
339                    .is_some_and(|b| b.len() > self.config.max_response_bytes)
340                {
341                    return Err(FetchError::Limit);
342                }
343                if matches!(response.status(), 301 | 302 | 303 | 307 | 308)
344                    && redirects < self.config.max_redirects
345                    && attempts < self.config.max_attempts
346                    && let Some(location) = response.headers().get("location")
347                {
348                    // Rejected redirects are returned, never followed or treated as transport failure.
349                    if let Ok(next) = req.redirect(location) {
350                        req = next;
351                        redirects += 1;
352                        continue;
353                    }
354                }
355                let action = self.hooks.process(&req, response).await?;
356                let (response, delay) = match action {
357                    FetchAction::Return(r) => {
358                        let delay = if r.status() == 429 {
359                            // HTTP Retry-After delta is seconds, correcting the source's millisecond interpretation.
360                            let delay = match r.headers().get("retry-after") {
361                                Some(s)
362                                    if !s.is_empty() && s.bytes().all(|b| b.is_ascii_digit()) =>
363                                {
364                                    s.parse::<u64>()
365                                        .ok()
366                                        .and_then(|n| n.checked_mul(1000))
367                                        .unwrap_or(u64::MAX)
368                                }
369                                _ => {
370                                    u64::from(self.config.retry_delay_ms)
371                                        * (1u64 << attempts.saturating_sub(1).min(11))
372                                }
373                            };
374                            Some(delay)
375                        } else {
376                            None
377                        };
378                        (r, delay)
379                    }
380                    FetchAction::Retry { response, delay_ms } => {
381                        (response, Some(u64::from(delay_ms)))
382                    }
383                };
384                if response
385                    .body()
386                    .is_some_and(|b| b.len() > self.config.max_response_bytes)
387                {
388                    return Err(FetchError::Limit);
389                }
390                if let Some(delay) = delay {
391                    // Locally resolved resources are processed once; retry is for actual exchanges.
392                    if attempts > 0
393                        && attempts < self.config.max_attempts
394                        && (matches!(req.method(), "GET" | "HEAD")
395                            || self.config.retry_non_idempotent)
396                        && self.hooks.retry(&req, &response, attempts).await?
397                    {
398                        let delay = delay.min(u64::from(self.config.timeout_ms));
399                        if delay > 0 {
400                            self.backend.sleep(delay as u32).await?;
401                        }
402                        continue;
403                    }
404                }
405                return Ok(FetchedResource {
406                    original: request.clone(),
407                    request: req,
408                    response,
409                    attempts,
410                });
411            }
412        };
413        let mut work = std::pin::pin!(work);
414        std::future::poll_fn(|cx| {
415            if let Err(e) = cancel.check(cx.waker()) {
416                return Poll::Ready(Err(e));
417            }
418            match expired() {
419                Ok(true) => return Poll::Ready(Err(FetchError::Timeout)),
420                Err(e) => return Poll::Ready(Err(e)),
421                _ => {}
422            }
423            if let Poll::Ready(r) = deadline.as_mut().poll(cx) {
424                return Poll::Ready(Err(r.err().unwrap_or(FetchError::Timeout)));
425            }
426            let result = work.as_mut().poll(cx);
427            if result.is_ready() {
428                if cancel.cancelled() {
429                    return Poll::Ready(Err(FetchError::Cancelled));
430                }
431                match expired() {
432                    Ok(true) => return Poll::Ready(Err(FetchError::Timeout)),
433                    Err(e) => return Poll::Ready(Err(e)),
434                    _ => {}
435                }
436            }
437            result
438        })
439        .await
440    }
441}