apisdk 0.0.1

A highlevel API client framework for Rust.
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
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

mod multi;
mod single;

use multi::*;
use single::*;

use crate::{async_trait, RouteError, Url};

/// This trait is used to generate an endpoint for each request
///
/// # Examples
///
/// ```
/// #[derive(Debug)]
/// struct EnvBasedRouter;
///
/// #[async_trait]
/// impl ApiRouter for EnvBasedRouter {
///     async fn next_endpoint(&self) -> Result<Box<dyn ApiEndpoint>, RouteError> {
///         let env = std::env::var_os("ENV")
///             .map(|v| v.to_string_lossy().to_uppercase())
///             .unwrap_or_default();
///         if env == "PROD" {
///             Ok(Box::new(DefaultApiEndpoint::new_default("1.1.1.1", 80)))
///         } else {
///             Ok(Box::new(DefaultApiEndpoint::new_default("2.2.2.2", 80)))
///         }
///     }
/// }
/// ```
#[async_trait]
pub trait ApiRouter: 'static + Sync + std::fmt::Debug {
    /// Indicate whether the HOST header should be rewritten.
    /// As default, we keep the original HOST from original url.
    fn rewrite_host(&self) -> bool {
        false
    }

    /// Generate endpoint
    async fn next_endpoint(&self) -> Result<Box<dyn ApiEndpoint>, RouteError>;
}

/// This struct provides several built-in implements of `ApiRouter`
pub struct ApiRouters;

impl ApiRouters {
    /// Initiate a fixed ApiRouter
    pub fn fixed(endpoint: impl Into<DefaultApiEndpoint>) -> impl ApiRouter {
        SingleApiRouter::new(endpoint.into())
    }

    /// Initiate a round robin ApiRouter for multiply endpoints
    pub fn round_robin(endpoints: &[DefaultApiEndpoint]) -> impl ApiRouter {
        MultiApiRouter::new_round_robin(endpoints)
    }

    /// Initiate a random ApiRouter for multiply endpoints
    pub fn random(endpoints: &[DefaultApiEndpoint]) -> impl ApiRouter {
        MultiApiRouter::new_random(endpoints)
    }
}

/// This trait is used to build urls
pub trait ApiEndpoint {
    /// Build request url
    /// - base: original base url
    /// - path: relative path
    fn build_url(&self, base: &Url, path: &str) -> Result<Url, RouteError>;

    /// Merge base url and path
    /// - base: base url
    /// - path: relative path
    fn merge_path(&self, base: &mut Url, path: &str) {
        let base_path = base.path();
        let new_path = match (base_path.ends_with('/'), path.starts_with('/')) {
            (true, true) => format!("{}{}", base_path, &path[1..]),
            (true, false) | (false, true) => format!("{}{}", base_path, path),
            (false, false) => format!("{}/{}", base_path, path),
        };
        base.set_path(&new_path);
    }
}

/// This endpoint keep original base url from ApiCore
pub struct OriginalEndpoint;

impl ApiEndpoint for OriginalEndpoint {
    fn build_url(&self, base: &Url, path: &str) -> Result<Url, RouteError> {
        let mut url = base.clone();
        self.merge_path(&mut url, path);
        Ok(url)
    }
}

/// This struct is a default implementation of `ApiEndpoint`
#[derive(Debug, Clone)]
pub struct DefaultApiEndpoint {
    scheme: Option<String>,
    host: String,
    port: u16,
}

impl DefaultApiEndpoint {
    pub fn new_default(host: impl ToString, port: u16) -> Self {
        Self::new(None::<&str>, host, port)
    }

    pub fn new_http(host: impl ToString, port: u16) -> Self {
        Self::new(Some("http"), host, port)
    }

    pub fn new_https(host: impl ToString, port: u16) -> Self {
        Self::new(Some("https"), host, port)
    }

    pub fn new(scheme: Option<impl ToString>, host: impl ToString, port: u16) -> Self {
        Self {
            scheme: scheme.map(|s| s.to_string()),
            host: host.to_string(),
            port,
        }
    }
}

impl<T> From<(T, u16)> for DefaultApiEndpoint
where
    T: ToString,
{
    fn from((host, port): (T, u16)) -> Self {
        Self::new_default(host, port)
    }
}

impl ApiEndpoint for DefaultApiEndpoint {
    fn build_url(&self, base: &Url, path: &str) -> Result<Url, RouteError> {
        let mut url = base.clone();
        if let Some(scheme) = self.scheme.as_ref() {
            url.set_scheme(scheme.as_str())
                .map_err(|_| RouteError::UpdateScheme(base.clone(), scheme.clone()))?;
        }
        url.set_host(Some(self.host.as_str()))
            .map_err(|e| RouteError::UpdateHost(base.clone(), self.host.clone(), e))?;
        url.set_port(Some(self.port))
            .map_err(|_| RouteError::UpdatePort(base.clone(), self.port))?;
        self.merge_path(&mut url, path);
        Ok(url)
    }
}