hitbox-core 0.2.2

Asynchronous caching framework core traits.
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

//! Upstream service abstraction.
//!
//! This module provides the [`Upstream`] trait for calling backend services
//! when cache misses occur.
//!
//! ## Overview
//!
//! The `Upstream` trait abstracts over any async service that can handle
//! requests and return responses. This allows the caching layer to be
//! agnostic to the actual service implementation.
//!
//! ## Framework Integration
//!
//! Protocol-specific crates provide implementations for common frameworks:
//!
//! - `hitbox-reqwest` - Reqwest HTTP client integration
//! - `hitbox-tower` - Tower service integration

use std::future::Future;

/// Trait for calling upstream services with cacheable requests.
///
/// This trait is framework-agnostic and can be implemented for any async service.
///
/// # Examples
///
/// ```rust,ignore
/// use hitbox_core::Upstream;
/// use std::future::Ready;
///
/// struct MockUpstream {
///     response: MyResponse,
/// }
///
/// impl Upstream<MyRequest> for MockUpstream {
///     type Response = MyResponse;
///     type Future = Ready<Self::Response>;
///
///     fn call(&mut self, _req: MyRequest) -> Self::Future {
///         std::future::ready(self.response.clone())
///     }
/// }
/// ```
pub trait Upstream<Req> {
    /// The response type returned by the upstream service
    type Response;

    /// The future that resolves to the response
    type Future: Future<Output = Self::Response> + Send;

    /// Call the upstream service with the given request
    fn call(&mut self, req: Req) -> Self::Future;
}