racal 0.5.0

REST API client abstraction library
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

//! An optional API client feature using `reqwest`
//!
//! Besides using this, you could instead easily implement your own client using
//! a different HTTP library with the [`racal::Queryable`](crate::Queryable)
//! trait.

use reqwest::{Client, RequestBuilder, Response};
use serde::de::DeserializeOwned;
use thiserror::Error;

use crate::{FromApiState, Queryable, RequestMethod};

/// An error that may happen with an API query
#[derive(Debug, Error)]
pub enum ApiError {
	/// An error happened with serialization
	#[error("An error happened with serialization: {0}")]
	Serde(serde_json::Error),

	/// An error happened with the request itself
	#[error("An error happened with the request itself: {0}")]
	Reqwest(reqwest::Error),
}

impl From<serde_json::Error> for ApiError {
	fn from(err: serde_json::Error) -> Self { Self::Serde(err) }
}

impl From<reqwest::Error> for ApiError {
	fn from(err: reqwest::Error) -> Self { Self::Reqwest(err) }
}

/// An API client that can be used to create queries
#[async_trait::async_trait]
pub trait ApiClient<State> {
	/// Gets the API state
	fn state(&self) -> &State;

	/// Gets the actual reqwest client
	fn client(&self) -> &Client;

	/// A way to modify the request right before sending it
	///
	/// Can also for example be used to implement rate limits thanks to the async
	/// nature
	async fn before_request(
		&self, req: RequestBuilder,
	) -> Result<RequestBuilder, ApiError> {
		Ok(req)
	}

	/// A way to modify the request after it's been received
	///
	/// By default errors on bad status messages and just deserializes the value,
	/// using the queryable.
	///
	/// Can also for example be used to implement rate limits thanks to the async
	/// nature.
	async fn handle_response<ReturnType, FromState, QueryableType>(
		&self, queryable: QueryableType, response: Response,
	) -> Result<ReturnType, ApiError>
	where
		ReturnType: DeserializeOwned,
		FromState: FromApiState<State>,
		QueryableType: Queryable<FromState, ReturnType> + Send + Sync,
	{
		let response = response.error_for_status()?;
		let val = response.bytes().await?;
		Ok(queryable.deserialize(&val)?)
	}

	/// Creates a query
	async fn query<ReturnType, FromState, QueryableType>(
		&self, queryable: QueryableType,
	) -> Result<ReturnType, ApiError>
	where
		ReturnType: DeserializeOwned,
		FromState: FromApiState<State>,
		QueryableType: Queryable<FromState, ReturnType> + Send + Sync,
	{
		let request = Self::build_request(
			self.client(),
			FromState::from_state(self.state()),
			&queryable,
		)?;
		let request = self.before_request(request).await?;
		let response = request.send().await?;

		self.handle_response(queryable, response).await
	}

	/// Builds the base request
	///
	/// # Errors
	///
	/// If body cannot be set for the request
	fn build_request<ReturnType, FromState, QueryableType>(
		http: &Client, api_state: &FromState, queryable: &QueryableType,
	) -> Result<RequestBuilder, ApiError>
	where
		ReturnType: DeserializeOwned,
		FromState: FromApiState<State>,
		QueryableType: Queryable<FromState, ReturnType> + Send + Sync,
	{
		let mut request = http.request(
			match queryable.method(api_state) {
				RequestMethod::Get => reqwest::Method::GET,
				RequestMethod::Head => reqwest::Method::HEAD,
				RequestMethod::Patch => reqwest::Method::PATCH,
				RequestMethod::Post => reqwest::Method::POST,
				RequestMethod::Put => reqwest::Method::PUT,
				RequestMethod::Delete => reqwest::Method::DELETE,
			},
			queryable.url(api_state),
		);
		if let Some(body) = queryable.body(api_state) {
			request = request.body(body?).header("Content-Type", "application/json");
		}

		Ok(request)
	}
}