hitbox_core/upstream.rs
1//! Upstream service abstraction.
2//!
3//! This module provides the [`Upstream`] trait for calling backend services
4//! when cache misses occur.
5//!
6//! ## Overview
7//!
8//! The `Upstream` trait abstracts over any async service that can handle
9//! requests and return responses. This allows the caching layer to be
10//! agnostic to the actual service implementation.
11//!
12//! ## Framework Integration
13//!
14//! Protocol-specific crates provide implementations for common frameworks:
15//!
16//! - `hitbox-reqwest` - Reqwest HTTP client integration
17//! - `hitbox-tower` - Tower service integration
18
19use std::future::Future;
20
21/// Trait for calling upstream services with cacheable requests.
22///
23/// This trait is framework-agnostic and can be implemented for any async service.
24///
25/// # Examples
26///
27/// ```rust,ignore
28/// use hitbox_core::Upstream;
29/// use std::future::Ready;
30///
31/// struct MockUpstream {
32/// response: MyResponse,
33/// }
34///
35/// impl Upstream<MyRequest> for MockUpstream {
36/// type Response = MyResponse;
37/// type Future = Ready<Self::Response>;
38///
39/// fn call(&mut self, _req: MyRequest) -> Self::Future {
40/// std::future::ready(self.response.clone())
41/// }
42/// }
43/// ```
44pub trait Upstream<Req> {
45 /// The response type returned by the upstream service
46 type Response;
47
48 /// The future that resolves to the response
49 type Future: Future<Output = Self::Response> + Send;
50
51 /// Call the upstream service with the given request
52 fn call(&mut self, req: Req) -> Self::Future;
53}