hitbox-http 0.2.1

Cacheable HTTP Request and Response
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
123
124
125
126
127
128
129
130

//! Header predicate implementation.

use async_trait::async_trait;
use hitbox::Neutral;
use hitbox::predicate::{Predicate, PredicateResult};
use http::HeaderMap;

use super::operation::Operation;

/// A predicate that matches HTTP headers against an [`Operation`].
///
/// Works with any subject implementing [`HasHeaders`], including both
/// requests and responses. Chain with other predicates using the builder pattern.
///
/// # Type Parameters
///
/// * `P` - The inner predicate to chain with. Use [`Header::new`] to start
///   a new predicate chain (uses [`Neutral`] internally), or use the
///   [`HeaderPredicate`] extension trait to chain onto an existing predicate.
///
/// # Examples
///
/// ```
/// use hitbox_http::predicates::header::{Header, Operation};
/// use http::header::CACHE_CONTROL;
///
/// # use bytes::Bytes;
/// # use http_body_util::Empty;
/// # use hitbox::Neutral;
/// # use hitbox_http::CacheableHttpRequest;
/// # type Subject = CacheableHttpRequest<Empty<Bytes>>;
/// // Skip caching when Cache-Control contains "no-cache"
/// let predicate = Header::new(Operation::Contains(
///     CACHE_CONTROL,
///     "no-cache".to_string(),
/// ));
/// # let _: &Header<Neutral<Subject>> = &predicate;
/// ```
#[derive(Debug)]
pub struct Header<P> {
    pub(crate) operation: Operation,
    pub(crate) inner: P,
}

impl<S> Header<Neutral<S>> {
    /// Creates a header predicate that matches headers against the operation.
    ///
    /// Returns [`Cacheable`](hitbox::predicate::PredicateResult::Cacheable) when
    /// the headers satisfy the operation, [`NonCacheable`](hitbox::predicate::PredicateResult::NonCacheable) otherwise.
    pub fn new(operation: Operation) -> Self {
        Self {
            operation,
            inner: Neutral::new(),
        }
    }
}

/// Extension trait for adding header matching to a predicate chain.
///
/// # For Callers
///
/// Chain this to add header matching to your predicate. The request or
/// response headers are inspected and matched against the provided [`Operation`].
///
/// # For Implementors
///
/// This trait is automatically implemented for all [`Predicate`](hitbox::predicate::Predicate)
/// types. You don't need to implement it manually.
pub trait HeaderPredicate: Sized {
    /// Adds a header matching operation to this predicate chain.
    fn header(self, operation: Operation) -> Header<Self>;
}

impl<P> HeaderPredicate for P
where
    P: Predicate,
{
    fn header(self, operation: Operation) -> Header<Self> {
        Header {
            operation,
            inner: self,
        }
    }
}

/// Trait for types that provide access to HTTP headers.
///
/// Implement this trait to enable header predicates on custom types.
/// Both [`CacheableHttpRequest`](crate::CacheableHttpRequest) and
/// [`CacheableHttpResponse`](crate::CacheableHttpResponse) implement this trait.
///
/// # For Implementors
///
/// Return a reference to the headers associated with the HTTP message.
/// The returned headers should reflect the current state of the message
/// and remain valid for the lifetime of the borrow.
///
/// # For Callers
///
/// Use this trait to access headers generically from either requests or
/// responses. Header predicates use this to inspect headers without knowing
/// the concrete message type.
pub trait HasHeaders {
    /// Returns a reference to the HTTP headers.
    fn headers(&self) -> &HeaderMap;
}

// Generic implementation for any subject that has headers
#[async_trait]
impl<P> Predicate for Header<P>
where
    P: Predicate + Send + Sync,
    P::Subject: HasHeaders + Send,
{
    type Subject = P::Subject;

    async fn check(&self, subject: Self::Subject) -> PredicateResult<Self::Subject> {
        match self.inner.check(subject).await {
            PredicateResult::Cacheable(subject) => {
                let is_cacheable = self.operation.check(subject.headers());
                if is_cacheable {
                    PredicateResult::Cacheable(subject)
                } else {
                    PredicateResult::NonCacheable(subject)
                }
            }
            PredicateResult::NonCacheable(subject) => PredicateResult::NonCacheable(subject),
        }
    }
}