Merge pull request #58 from CleverCloud/clg/refactor

refactor

Author: FlorentinDUBOIS

Cargo.toml

@@ -4,20 +4,44 @@ description = "A rust implementation of the oauth 1.0a protocol fully-async with
 version = "2.1.2"
 edition = "2024"
 rust-version = "1.85.0"
-authors = ["Florentin Dubois <[email protected]>"]
+authors = [
+    "Florentin Dubois <[email protected]>",
+    "Cédric Lemaire-Giroud <[email protected]>",
+]
 license-file = "LICENSE"
 readme = "README.md"
 repository = "https://github.com/CleverCloud/oauth10a-rust"
 keywords = ["clevercloud", "client", "logging", "metrics", "oauth1a"]
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
+[features]
+default = ["logging", "client"]
+tracing = ["dep:tracing"]
+logging = ["log", "tracing/log-always"]
+metrics = ["dep:prometheus"]
+execute = []
+client = ["execute"]
+rest = ["execute", "dep:serde", "dep:serde_json"]
+sse = [
+    "execute",
+    "dep:serde",
+    "dep:serde_json",
+    "dep:bytes",
+    "dep:futures",
+    "dep:mime",
+    "dep:memchr",
+    "dep:tokio",
+]
+serde = ["dep:serde"]
+zeroize = ["dep:zeroize"]
+
 [dependencies]
-base64 = { version = "^0.22.1", optional = true }
-bytes = { version = "^1.10.1", features = ["serde"], optional = true }
-crypto-common = { version = "^0.1.6", optional = true }
+base64 = { version = "^0.22.1" }
+bytes = { version = "^1.10.1", optional = true }
+crypto-common = { version = "^0.1.6" }
 futures = { version = "^0.3.31", optional = true }
-hmac = { version = "^0.12.1", features = ["std"], optional = true }
+hmac = { version = "^0.12.1" }
 log = { version = "^0.4.27", optional = true }
 memchr = { version = "^2.7.4", optional = true }
 mime = { version = "^0.3.17", optional = true }
@@ -32,46 +56,24 @@ reqwest = { version = "^0.12.15", default-features = true, features = [
     "json",
     "hickory-dns",
     "stream",
-], optional = true }
+] }
 serde = { version = "^1.0.219", features = ["derive"], optional = true }
 serde_json = { version = "^1.0.140", features = [
     "preserve_order",
     "float_roundtrip",
 ], optional = true }
-sha2 = { version = "^0.10.9", optional = true }
-thiserror = { version = "^2.0.12", optional = true }
-tokio = { version = "^1.44.2", optional = true, default-features = false, features = [
+sha2 = { version = "^0.10.9" }
+thiserror = { version = "^2.0.12" }
+tokio = { version = "^1.45.1", optional = true, default-features = false, features = [
     "time",
 ] }
 tracing = { version = "^0.1.41", optional = true }
-url = { version = "^2.5.4", default-features = false, features = [
-    "serde",
-], optional = true }
-urlencoding = { version = "^2.1.3", optional = true }
-uuid = { version = "^1.16.0", features = ["serde", "v4"], optional = true }
+url = { version = "2.5.4", features = ["serde"] }
+urlencoding = { version = "^2.1.3" }
+uuid = { version = "^1.17.0", features = ["serde", "v4"] }
+zeroize = { version = "^1.8.1", features = ["derive"], optional = true }
 
 [dev-dependencies]
 anyhow = { version = "^1.0.98" }
 axum = { version = "^0.8.4" }
-tokio = { version = "^1.44.2", features = ["full"] }
-
-[features]
-default = ["client", "logging"]
-client = [
-    "base64",
-    "bytes",
-    "crypto-common",
-    "hmac",
-    "reqwest",
-    "serde",
-    "serde_json",
-    "sha2",
-    "thiserror",
-    "url",
-    "urlencoding",
-    "uuid",
-]
-logging = ["log", "tracing/log-always"]
-tracing = ["dep:tracing"]
-metrics = ["prometheus"]
-sse = ["dep:futures", "dep:mime", "dep:memchr", "dep:tokio"]
+tokio = { version = "^1.45.1", features = ["full"] }

README.md

@@ -1,59 +1,77 @@
 # OAuth 1.0a crate
 
-> This crate provides an oauth 1.0a client implementation fully-async with
+> This crate provides an OAuth 1.0a client implementation fully-async with
 > logging, metrics and tracing facilities. It was firstly designed to interact
-> with the Clever-Cloud's api, but has been extended to be more generic.
+> with the Clever-Cloud's API, but has been extended to be more generic.
 
 ## Status
 
-This crate is ready for production, if you may have bugs, so please an issue to
-fix the trouble.
+This crate is ready for production. If you find a bug, please open an issue.
 
 ## Installation
 
 To install this dependency, just add the following line to your `Cargo.toml` manifest.
 
 ```toml
-oauth10a = { version = "^1.5.1", features = ["metrics"] }
+oauth10a = { version = "^2.1.2", features = ["metrics"] }
 ```
 
 ## Usage
 
-Below, you will find an example of executing a simple request to an api.
+Below, you will find an example of executing a simple request to an API.
 
 ```rust
-use std::error::Error;
+use oauth10a::{client::Client, credentials::Credentials, rest::RestClient};
 
-use oauth10a::client::{Client, Credentials, RestClient};
+type MyData = std::collections::BTreeMap<String, String>;
+type MyError = String;
 
 #[tokio::main]
-async fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
-    let client = Client::from(Credentials::oauth1("".to_string(), "".to_string(), "".to_string(), "".to_string()));
-    let _obj: BtreeMap<String, String> = client.get("https://example.com/object.json").await?;
+async fn main() -> Result<(), Box<dyn core::error::Error + Send + Sync>> {
+    let client = Client::new().with_credentials(Credentials::OAuth1 {
+        token: "",
+        secret: "",
+        consumer_key: "",
+        consumer_secret: "",
+    });
+
+    match client.get::<MyData, MyError>("https://example.com/object.json").await {
+        // received HTTP response with JSON payload deserializing to `MyData`
+        Ok(Ok(response)) => (),
+        // received HTTP error response with JSON payload deserializing to `MyError`
+        Ok(Err(error_response)) => (),
+        // client failed to execute request
+        Err(rest_error) => ()
+    }
 
     Ok(())
 }
 ```
 
 ## Features
 
-| name    | description                                                   |
-|---------|---------------------------------------------------------------|
-| default | Default enable features are `client` and `logging`            |
-| client  | The oauth 1.0a client implementation                          |
-| logging | Use the `log` facility crate to print logs                    |
-| metrics | Use `prometheus` crates to register metrics                   |
-| tracing | Use `tracing` crate to add `tracing::instrument` on functions |
-| sse     | Enables streaming Server-Sent Events (SSE)                    |
+| name    | description                                                                               |
+| ------- | ----------------------------------------------------------------------------------------- |
+| default | Default enable features are `client` and `logging`                                        |
+| execute | Provides the `ExecuteRequest` trait                                                       |
+| client  | Provides an HTTP client that implements `ExecuteRequest` handling request's authorization |
+| logging | Use the `log` facility crate to print logs                                                |
+| metrics | Use `prometheus` crate to register metrics                                                |
+| tracing | Use `tracing` crate to add `tracing::instrument` on functions                             |
+| rest    | Enables RESTful API helper methods                                                        |
+| sse     | Enables streaming Server-Sent Events (SSE)                                                |
+| serde   | Provides `serde` implementation for `Credentials`                                         |
+| zeroize | Provides `zeroize::Zeroize` implementations on `Credentials`                              |
 
 ### Metrics
 
 Below, the exposed metrics gathered by prometheus:
 
-| name                             | labels                                                          | kind    | description                |
-| -------------------------------- | --------------------------------------------------------------- | ------- | -------------------------- |
-| oauth10a_client_request          | endpoint: String, method: String, status: Integer               | Counter | number of request on api   |
-| oauth10a_client_request_duration | endpoint: String, method: String, status: Integer, unit: String | Counter | duration of request on api |
+| name                             | labels                                                          | kind    | description                        |
+| -------------------------------- | --------------------------------------------------------------- | ------- | ---------------------------------- |
+| oauth10a_client_request          | endpoint: String, method: String, status: Integer               | Counter | number of request on API           |
+| oauth10a_client_request_duration | endpoint: String, method: String, status: Integer, unit: String | Counter | duration of request on API         |
+| oauth10a_client_sse              | endpoint: String                                                | Counter | number of events received from API |
 
 ## License
 

src/client.rs

@@ -0,0 +1,146 @@
+//! HTTP client
+
+use core::fmt;
+
+use reqwest::{Request, Response};
+
+use crate::{
+    credentials::{AuthorizationError, Credentials},
+    execute::ExecuteRequest,
+};
+
+// CLIENT ERROR ////////////////////////////////////////////////////////////////
+
+#[derive(Debug, thiserror::Error)]
+pub enum ClientError<E = reqwest::Error> {
+    #[error("failed to authorize request, {0}")]
+    Authorize(#[from] AuthorizationError),
+    #[error("failed to execute request, {0}")]
+    Execute(E),
+}
+
+// CLIENT //////////////////////////////////////////////////////////////////////
+
+/// HTTP client with optional [`Credentials`].
+///
+/// When credentials are provided, the client, will ensure requests are authorized
+/// before they are executed.
+#[derive(Debug, Default, Clone)]
+#[must_use]
+pub struct Client<T = reqwest::Client> {
+    inner: T,
+    credentials: Option<Credentials>,
+}
+
+impl<T> From<T> for Client<T> {
+    fn from(value: T) -> Self {
+        Self {
+            inner: value,
+            credentials: None,
+        }
+    }
+}
+
+impl From<&Credentials> for Client {
+    fn from(value: &Credentials) -> Self {
+        Self::from(value.clone())
+    }
+}
+
+impl<T: Into<Box<str>>> From<Credentials<T>> for Client {
+    fn from(value: Credentials<T>) -> Self {
+        Self {
+            inner: reqwest::Client::new(),
+            credentials: Some(value.into()),
+        }
+    }
+}
+
+impl Client {
+    pub fn new() -> Self {
+        Self::default()
+    }
+}
+
+impl<T: fmt::Debug> Client<T> {
+    /// Sets the `credentials` to be used by the client to authorize HTTP request,
+    /// discarding the current value, if any.
+    #[cfg_attr(feature = "tracing", tracing::instrument)]
+    pub fn set_credentials(&mut self, credentials: Option<Credentials>) {
+        self.credentials = credentials;
+    }
+
+    #[cfg_attr(feature = "tracing", tracing::instrument)]
+    fn set_credentials_from<U: Into<Box<str>> + fmt::Debug>(
+        &mut self,
+        credentials: Option<Credentials<U>>,
+    ) {
+        self.credentials = credentials.map(Credentials::into);
+    }
+
+    /// Fills the `credentials` to be used by the client to authorize HTTP request,
+    /// discarding the current value, if any.
+    pub fn with_credentials<U: Into<Box<str>> + fmt::Debug>(
+        mut self,
+        credentials: impl Into<Option<Credentials<U>>>,
+    ) -> Self {
+        self.set_credentials_from(credentials.into());
+        self
+    }
+
+    /// Returns the credentials that will be used by this client to authorized
+    /// subsequent HTTP requests.
+    #[cfg_attr(feature = "tracing", tracing::instrument)]
+    pub fn credentials(&self) -> Option<Credentials<&str>> {
+        self.credentials.as_ref().map(Credentials::as_ref)
+    }
+
+    /// Returns a shared reference to the inner HTTP client.
+    #[cfg_attr(feature = "tracing", tracing::instrument)]
+    pub fn inner(&self) -> &T {
+        &self.inner
+    }
+
+    /// Appends an `Authorization` header to the `request`, if this client has credentials and unless it is already set.
+    ///
+    /// Returns `true` if the `Authorization` header was inserted.
+    ///
+    /// # Errors
+    ///
+    /// Upon failure to produce the header value.
+    ///
+    /// If the client doesn't have credentials, this method is infallible.
+    #[cfg_attr(feature = "tracing", tracing::instrument)]
+    pub fn authorize(&self, request: &mut Request) -> Result<bool, AuthorizationError> {
+        match self.credentials() {
+            None => Ok(false),
+            Some(credentials) => credentials.authorize(request),
+        }
+    }
+}
+
+impl<T: ExecuteRequest> ExecuteRequest for Client<T> {
+    type Error = ClientError<T::Error>;
+
+    fn execute_request(
+        &self,
+        mut request: Request,
+    ) -> impl Future<Output = Result<Response, Self::Error>> + Send + 'static {
+        let result = self
+            .authorize(&mut request)
+            .map(|_| self.inner.execute_request(request));
+
+        async move { result?.await.map_err(ClientError::Execute) }
+    }
+}
+
+#[cfg(feature = "zeroize")]
+impl<T> Drop for Client<T> {
+    fn drop(&mut self) {
+        use zeroize::Zeroize;
+
+        if let Some(mut credentials) = self.credentials.take() {
+            credentials.zeroize();
+        }
+    }
+}