rama-ua 0.3.0

user-agent (UA) support for rama
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

use rama_core::error::BoxErrorExt as _;
use rama_core::error::{BoxError, ErrorExt as _};
use rama_core::extensions::Extension;
use rama_http::headers::ClientHint;
use rama_utils::macros::match_ignore_ascii_case_str;
use std::sync::Arc;
use std::{fmt, ops::Deref, str::FromStr};

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, Extension)]
#[extension(tags(ua))]
#[non_exhaustive]
/// Runtime hint to request a user agent to be preserved,
/// useful for systems that modify requests based on the context and request,
/// but still wish to support preserving the original header user-agent.
///
/// Used by [`UserAgentEmulateService`].
///
/// [`UserAgentEmulateService`]: crate::layer::emulate::UserAgentEmulateService
pub struct PreserveHeaderUserAgent;

impl PreserveHeaderUserAgent {
    #[inline]
    /// Create a new [`PreserveHeaderUserAgent`].
    #[must_use]
    pub fn new() -> Self {
        Default::default()
    }
}

/// ClientHints requested for the (http) Request.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Default, Extension)]
#[extension(tags(ua))]
pub struct RequestClientHints(pub Arc<[ClientHint]>);

impl AsRef<[ClientHint]> for RequestClientHints {
    fn as_ref(&self) -> &[ClientHint] {
        self.0.deref()
    }
}

impl Deref for RequestClientHints {
    type Target = [ClientHint];

    fn deref(&self) -> &Self::Target {
        self.0.deref()
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Extension)]
#[extension(tags(ua))]
/// The initiator of the (http) Request.
///
/// It is used to determine the request initiator for the to be emulated http request,
/// and can either be attempted to be detected or manually injected into the [`Extensions`],
/// or implicitly via a layer service to extract that info from a custom http header.
///
/// It is used by [`UserAgentEmulateHttpRequestModifier`] to determine the request initiator
/// for the to be emulated http request, and indicates the preferred headers to use from
/// the [`HttpHeadersProfile`] to emulate the request.
///
/// [`Extensions`]: rama_core::extensions::Extensions
/// [`UserAgentEmulateHttpRequestModifier`]: crate::layer::emulate::UserAgentEmulateHttpRequestModifier
/// [`HttpHeadersProfile`]: crate::profile::HttpHeadersProfile
pub enum RequestInitiator {
    /// normal navigate, expexted by all [`super::UserAgentProfile`] to be implemented
    Navigate,
    /// form action, considered optional (e.g. native non-browser user-agents typically don't support this)
    Form,
    /// XML Http Request (Original Ajax tech in browsers), to fetch content from (Js) scripts,
    /// considered optional (e.g. a very modern non-browser user-agent might support only the more
    /// modern Fetch API without backwards compatibility for the older XMLHttpRequest API)
    Xhr,
    /// Fetch API ("Modern" async-able approach to fetch content from (Js) scripts),
    /// optional and for example not supported by user-agents that are only capable of
    /// handling regular navigate requests or do not support more than one request type.
    Fetch,
    /// WebSocket Upgrade Request
    Ws,
}

impl RequestInitiator {
    /// Get the string representation of the request initiator.
    #[must_use]
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Navigate => "navigate",
            Self::Form => "form",
            Self::Xhr => "xhr",
            Self::Fetch => "fetch",
            Self::Ws => "ws",
        }
    }
}

impl fmt::Display for RequestInitiator {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.as_str())
    }
}

use rama_utils::macros::serde_str::impl_serde_str;

impl_serde_str!(as_str RequestInitiator);

impl FromStr for RequestInitiator {
    type Err = BoxError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match_ignore_ascii_case_str! {
            match (s) {
                "navigate" => Ok(Self::Navigate),
                "form" => Ok(Self::Form),
                "xhr" => Ok(Self::Xhr),
                "fetch" => Ok(Self::Fetch),
                _ => Err(BoxError::from_static_str("invalid request initiator").context_str_field("str", s)),
            }
        }
    }
}