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
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
use crate::errors::Error;
use log::debug;
use reqwest::Response;
use reqwest::header::{AUTHORIZATION, HeaderMap, HeaderName, HeaderValue};
use rustsf_auth::{SalesforceAuthSession, SalesforceCredentials};
use serde::Serialize;
use std::collections::HashMap;
use std::fmt::Debug;
#[cfg(feature = "metadata-api")]
use reqwest::multipart::Form;
pub const DEFAULT_API_VERSION: &str = "68.0";
pub const CONNECT_TIMEOUT: u64 = 15;
pub const REQUEST_TIMEOUT: u64 = 30;
pub struct Client {
http_client: reqwest::Client,
session: SalesforceAuthSession,
}
impl Client {
pub async fn new(session: SalesforceCredentials) -> Result<Self, Error> {
let http_client = reqwest::Client::builder()
.redirect(reqwest::redirect::Policy::none())
.connect_timeout(std::time::Duration::from_secs(CONNECT_TIMEOUT))
.timeout(std::time::Duration::from_secs(REQUEST_TIMEOUT))
.build()?;
Ok(Self {
http_client,
session: session.connect().await?,
})
}
#[cfg(feature = "metadata-api")]
pub async fn access_token(&self) -> Result<String, Error> {
Ok(self.session.access_token().await?)
}
/// Sends an asynchronous HTTP DELETE request to a specified path.
///
/// # Parameters
/// - `path` (`String`): The path to which the DELETE request will be sent. This path will be appended to the instance URL.
///
/// # Returns
/// - `Result<Response, Error>`:
/// - On success, returns an `Ok(Response)` representing the HTTP response from the server.
/// - On failure, returns an `Err(Error)` detailing the error encountered.
///
/// # Errors
/// - This function will return an error in the following scenarios:
/// - If the client is not logged in (`Error::NotLoggedIn`).
/// - If refreshing the client token fails.
/// - If there is an issue creating the HTTP headers.
/// - If the HTTP request fails during execution.
///
/// # Async Behavior
/// - This function is asynchronous and should be awaited.
/// - Before sending the DELETE request, it ensures that the client state is up-to-date by calling `self.ensure_refresh()`.
///
pub async fn delete(&self, url: &str, headers: &HashMap<String, String>) -> Result<Response, Error> {
debug!("DELETE: {} headers: {:?}", url, headers);
let mut headers = self.create_header(headers).await?;
headers.insert("Content-Type", HeaderValue::from_static("application/json"));
let response = self.http_client.delete(url).headers(headers).send().await?;
debug!("DELETE response: {:?}", response);
Ok(response)
}
/// Sends an asynchronous HTTP GET request to the specified URL with the provided query parameters.
///
/// This function ensures that any necessary pre-request setup (such as refreshing tokens or credentials)
/// is performed before sending the request. It then constructs the request with appropriate headers and
/// query parameters, uses the underlying HTTP client to send the request, and returns the response or an error.
///
/// # Arguments
///
/// * `url` - A `String` representing the target URL for the GET request.
/// * `params` - A `Vec` of tuples where each tuple contains a key-value pair (`String`, `String`) representing
/// query parameters to append to the URL.
///
/// # Returns
///
/// Returns a `Result` containing:
/// - `Response`: The HTTP response object if the request is successful.
/// - `Error`: An error if an issue occurs during the process of refreshing credentials,
/// constructing the request, or sending it.
///
/// # Errors
///
/// This function can return an `Error` due to:
/// - Failure during the token/credential refresh process in `self.ensure_refresh()`.
/// - Issues with building headers in `self.create_header`.
/// - Errors originating from the underlying HTTP client's `send` function (e.g., connectivity issues).
pub async fn get_json<T: Debug + Serialize, S: AsRef<str> + reqwest::IntoUrl>(
&self,
url: S,
params: &T, // todo should be made optional, as some calls do not require this.
headers: &HashMap<String, String>,
) -> Result<Response, Error> {
debug!("GET: {} params: {:?} headers: {:?}", url.as_ref(), params, headers);
let mut headers = self.create_header(headers).await?;
headers.insert("Content-Type", HeaderValue::from_static("application/json"));
let response = self.http_client.get(url).headers(headers).query(¶ms).send().await?;
debug!("GET response: {:?}", response);
Ok(response)
}
#[cfg(feature = "bulk-api-v2")]
pub async fn get_raw(
&mut self,
url: &str,
additional_headers: &HashMap<String, String>,
) -> Result<Response, Error> {
debug!("GET: {} headers: {:?}", url, additional_headers);
let res = self
.http_client
.get(url)
.headers(self.create_header(additional_headers).await?)
.send()
.await?;
Ok(res)
}
pub(crate) fn instance_url(&self) -> &str {
&self.session.instance_url
}
pub fn org_id(&self) -> Option<&str> {
self.session.org_id.as_deref()
}
/// Sends a PATCH request to the specified REST API endpoint with the given parameters.
///
/// # Type Parameters
/// - `T`: The type of the parameters to be serialized into the request body. It must implement the `Serialize` trait.
///
/// # Arguments
/// - `path`: A `String` representing the relative path of the API endpoint to send the request to.
/// - `params`: An object of type `T` containing the parameters to be serialized into the JSON body of the request.
///
/// # Returns
/// - `Ok(Response)`: On a successful request, returns the HTTP response of type `Response`.
/// - `Err(Error)`: Returns an error if:
/// - The instance is not properly set up or the user is not logged in (`Error::NotLoggedIn`).
/// - There is an issue with refreshing the instance or creating the request headers.
/// - The HTTP request fails for some other reason (e.g., a network error).
///
/// # Errors
/// This method may return an error in the following cases:
/// - The user is not logged in (`Error::NotLoggedIn`) and the `instance_url` is unavailable.
/// - If the `ensure_refresh` internal function fails (e.g., unable to refresh client tokens).
/// - If there is an error serializing the parameters or constructing the HTTP headers.
/// - If the HTTP request fails during transmission or response handling.
pub async fn patch<T: Debug + Serialize>(
&self,
url: &str,
params: T,
headers: &HashMap<String, String>,
) -> Result<Response, Error> {
debug!("PATCH: {} params: {:?} headers: {:?}", url, params, headers);
let mut headers = self.create_header(headers).await?;
headers.insert("Content-Type", HeaderValue::from_static("application/json"));
Ok(self
.http_client
.patch(url)
.headers(headers)
.json(¶ms)
.send()
.await?)
}
pub async fn post_json<T: Debug + Serialize>(
&self,
url: &str,
data: &T,
headers: &HashMap<String, String>,
) -> Result<Response, Error> {
debug!("POST: {} params: {:?} headers: {:?}", url, data, headers);
let mut headers = self.create_header(headers).await?;
headers.insert("Content-Type", HeaderValue::from_static("application/json"));
Ok(self.http_client.post(url).headers(headers).json(&data).send().await?)
}
pub async fn post(&self, url: &str, data: Vec<u8>, headers: &HashMap<String, String>) -> Result<Response, Error> {
debug!("POST: {} headers: {:?}", url, headers);
Ok(self
.http_client
.post(url)
.headers(self.create_header(headers).await?)
.body(data)
.send()
.await?)
}
/// Asynchronously sends an HTTP POST multipart equest to the specified URL with the given parameters and headers.
///
/// This function ensures the client is refreshed before making the request.
/// It constructs the POST request by combining the given URL, serialization of parameters, and custom headers,
/// and uses the `reqwest` HTTP client to send the request.
///
/// # Type Parameters
///
/// * `T`: A type that implements the `Serialize` trait, representing the body of the POST request.
///
/// # Parameters
///
/// * `url` - A `String` representing the URL endpoint for the POST request.
/// * `headers` - A vector of tuples where each tuple contains a header name and its corresponding value (`Vec<(String, String)>`).
/// * `from` - A multipart form to include in the request.
///
/// # Returns
///
/// Returns a `Result`:
/// - `Ok(Response)` on success, where `Response` is the HTTP response returned by the request.
/// - `Err(Error)` if an error occurs during the request, such as serialization issues, header creation errors, or HTTP client errors.
///
/// Note: Ensure that the given `url` is valid and accessible and that proper error handling is implemented
/// for production use.
#[cfg(feature = "metadata-api")]
pub async fn post_multipart(
&self,
url: &str,
headers: &HashMap<String, String>,
form: Form,
) -> Result<Response, Error>
{
debug!("POST: {:?} form: {:?} headers: {:?}", url, form, headers);
let mut headers = self.create_header(headers).await?;
headers.insert("Accept", HeaderValue::from_static("application/json"));
let request = self.http_client.post(url).multipart(form).headers(headers).build()?;
let response = self.http_client.execute(request).await?;
Ok(response)
}
/// Sends an HTTP PUT request to the specified URL with the provided content.
///
/// This method ensures that necessary pre-request refresh actions are performed,
/// sets the proper headers (`Content-Type` as `text/csv` and `Accept` as `application/json`),
/// and sends the supplied data as the request body.
///
/// # Arguments
///
/// * `url` - A `String` containing the target URL for the PUT request.
/// * `buffer` - A `Vec<u8>` containing the binary data to be sent as the request body.
///
/// # Returns
///
/// This method returns a `Result`:
/// * `Ok(Response)` - The HTTP response returned by the server.
/// * `Err(Error)` - An error if the refresh action, header creation,
/// or the HTTP request itself fails.
///
/// # Errors
///
/// This function can return an error in the following cases:
/// * If the `ensure_refresh` method fails to complete successfully.
/// * If header creation fails to generate a valid set of headers.
/// * If the `http_client.put` request encounters an issue during sending or receiving.
pub async fn put<T: Into<reqwest::Body>>(&mut self, url: String, buffer: T) -> Result<Response, Error> {
debug!("PUT: {}", url);
let headers: HashMap<String, String> = HashMap::new();
let mut headers = self.create_header(&headers).await?;
headers.insert("Content-Type", HeaderValue::from_static("text/csv"));
headers.insert("Accept", HeaderValue::from_static("application/json"));
let res = self
.http_client
.put(url.as_str())
.headers(headers)
.body(buffer)
.send()
.await?;
Ok(res)
}
pub async fn post_soap(&self, action: &str, body: String) -> Result<Response, Error> {
let url = self.soap_version_path();
debug!("Soap Metadata API '{}' request: POST {} : {}", action, url, body);
Ok(self
.http_client
.post(url)
.header("Content-Type", "text/xml")
.header("SOAPAction", format!("'{}'", action))
.body(body)
.send()
.await?)
}
pub fn services_data_path(&self) -> String {
format!("{}/services/data", self.instance_url())
}
pub(crate) fn services_data_version_path(&self) -> String {
format!("{}/services/data/v{}", self.instance_url(), DEFAULT_API_VERSION)
}
pub fn soap_version_path(&self) -> String {
let instance_url = self.instance_url();
format!("{}/services/Soap/m/{}", instance_url, DEFAULT_API_VERSION)
}
pub fn user_id(&self) -> Option<&str> {
self.session.user_id.as_deref()
}
/// Generates a `HeaderMap` containing default headers, authorization, and additional custom headers.
///
/// # Arguments
///
/// * `additional_headers` - A list of key-value pairs representing additional headers
/// to be added to the request. Each key is the header name and each value is the corresponding header value.
///
/// # Returns
///
/// * `Ok(HeaderMap)` - Returns the constructed `HeaderMap` with all headers included.
/// * `Err(Error)` - Returns an error in the following scenarios:
/// - If the access token is not found (`Error::NotLoggedIn`).
/// - If a provided header name is invalid (`Error::ConfigError`).
/// - If a provided header value cannot be parsed.
///
/// # Behavior
///
/// - Authenticates the request by including an `Authorization` header with a Bearer token.
/// The token is retrieved from the `access_token` field of the struct, and an error is
/// returned if it is not available.
/// - Sets a default `Accept: application/json` header.
/// - Iterates through the `additional_headers` list and adds the headers
/// to the `HeaderMap`. If a header name already exists, the existing value is replaced.
/// - All header names are validated for correctness, and invalid header names or values will result in an error.
///
/// # Errors
///
/// - `Error::NotLoggedIn` occurs when there is no access token available.
/// - `Error::ConfigError` occurs if the custom header name is invalid or unparseable.
/// - Errors are propagated if the header value conversion fails.
///
async fn create_header(&self, additional_headers: &HashMap<String, String>) -> Result<HeaderMap, Error> {
let mut headers = HeaderMap::new();
let auth_value = format!("Bearer {}", self.session.access_token().await?);
headers.insert(AUTHORIZATION, HeaderValue::from_str(&auth_value)?);
for (key, value) in additional_headers {
let header_name: HeaderName = key.parse()?;
let header_value = HeaderValue::from_str(&value)?;
//delete duplicates
headers.remove(&header_name);
headers.insert(header_name, header_value);
}
Ok(headers)
}
}