slack_rs/api/
client.rs

1//! HTTP client for Slack API calls
2//!
3//! This module provides a configurable HTTP client with:
4//! - Configurable base URL (for testing with mock servers)
5//! - Retry logic with exponential backoff
6//! - Rate limit handling (429 + Retry-After)
7//! - Support for both wrapper commands and generic API calls
8
9use reqwest::{Client, Method, Response, StatusCode};
10use serde_json::Value;
11use std::collections::HashMap;
12use std::time::Duration;
13use thiserror::Error;
14
15use super::guidance::format_error_guidance;
16use super::types::{ApiMethod, ApiResponse};
17
18/// API client errors (for wrapper commands)
19#[derive(Error, Debug)]
20pub enum ApiError {
21    #[error("HTTP request failed: {0}")]
22    RequestFailed(#[from] reqwest::Error),
23
24    #[error("JSON serialization failed: {0}")]
25    JsonError(#[from] serde_json::Error),
26
27    #[error("Slack API error: {0}")]
28    SlackError(String),
29
30    #[allow(dead_code)]
31    #[error("Missing required parameter: {0}")]
32    MissingParameter(String),
33
34    #[error("Write operation denied. Set SLACKCLI_ALLOW_WRITE=true to enable write operations")]
35    WriteNotAllowed,
36
37    #[error("Destructive operation cancelled")]
38    OperationCancelled,
39
40    #[error("Non-interactive mode error: {0}")]
41    NonInteractiveError(String),
42}
43
44/// API client errors (for generic API calls)
45#[derive(Debug, Error)]
46pub enum ApiClientError {
47    #[error("HTTP request failed: {0}")]
48    RequestFailed(#[from] reqwest::Error),
49
50    #[error("Rate limit exceeded, retry after {0} seconds")]
51    RateLimitExceeded(u64),
52
53    #[error("API error: {0}")]
54    ApiError(String),
55
56    #[error("Invalid response: {0}")]
57    InvalidResponse(String),
58}
59
60pub type Result<T> = std::result::Result<T, ApiClientError>;
61
62/// Configuration for the API client
63#[derive(Debug, Clone)]
64pub struct ApiClientConfig {
65    /// Base URL for API calls (default: https://slack.com/api)
66    pub base_url: String,
67
68    /// Maximum number of retry attempts
69    pub max_retries: u32,
70
71    /// Initial backoff duration in milliseconds
72    pub initial_backoff_ms: u64,
73
74    /// Maximum backoff duration in milliseconds
75    pub max_backoff_ms: u64,
76}
77
78impl Default for ApiClientConfig {
79    fn default() -> Self {
80        Self {
81            base_url: "https://slack.com/api".to_string(),
82            max_retries: 3,
83            initial_backoff_ms: 1000,
84            max_backoff_ms: 32000,
85        }
86    }
87}
88
89/// Slack API client
90///
91/// Supports both:
92/// - Wrapper commands via `call_method()` with `ApiMethod` enum
93/// - Generic API calls via `call()` with arbitrary endpoints
94pub struct ApiClient {
95    client: Client,
96    pub(crate) token: Option<String>,
97    config: ApiClientConfig,
98}
99
100impl ApiClient {
101    /// Create a new API client with default configuration (for generic API calls)
102    pub fn new() -> Self {
103        Self::with_config(ApiClientConfig::default())
104    }
105
106    /// Create a new API client with a token (for wrapper commands)
107    pub fn with_token(token: String) -> Self {
108        Self {
109            client: Client::builder()
110                .timeout(Duration::from_secs(30))
111                .build()
112                .expect("Failed to create HTTP client"),
113            token: Some(token),
114            config: ApiClientConfig::default(),
115        }
116    }
117
118    /// Create a new API client with custom configuration
119    pub fn with_config(config: ApiClientConfig) -> Self {
120        let client = Client::builder()
121            .timeout(Duration::from_secs(30))
122            .build()
123            .expect("Failed to create HTTP client");
124
125        Self {
126            client,
127            token: None,
128            config,
129        }
130    }
131
132    /// Create a new API client with custom base URL (for testing)
133    #[doc(hidden)]
134    #[allow(dead_code)]
135    pub fn new_with_base_url(token: String, base_url: String) -> Self {
136        Self {
137            client: Client::new(),
138            token: Some(token),
139            config: ApiClientConfig {
140                base_url,
141                ..Default::default()
142            },
143        }
144    }
145
146    /// Get the base URL
147    pub fn base_url(&self) -> &str {
148        &self.config.base_url
149    }
150
151    /// Call a Slack API method using the ApiMethod enum (for wrapper commands)
152    pub async fn call_method(
153        &self,
154        method: ApiMethod,
155        params: HashMap<String, Value>,
156    ) -> std::result::Result<ApiResponse, ApiError> {
157        let token = self
158            .token
159            .as_ref()
160            .ok_or_else(|| ApiError::SlackError("No token configured".to_string()))?;
161
162        let url = format!("{}/{}", self.config.base_url, method.as_str());
163
164        let response = if method.uses_get_method() {
165            // Use GET request with query parameters
166            let mut query_params = vec![];
167            for (key, value) in params {
168                let value_str = match value {
169                    Value::String(s) => s,
170                    Value::Number(n) => n.to_string(),
171                    Value::Bool(b) => b.to_string(),
172                    _ => serde_json::to_string(&value).unwrap_or_default(),
173                };
174                query_params.push((key, value_str));
175            }
176
177            self.client
178                .get(&url)
179                .bearer_auth(token)
180                .query(&query_params)
181                .send()
182                .await?
183        } else {
184            // Use POST request with JSON body
185            self.client
186                .post(&url)
187                .bearer_auth(token)
188                .json(&params)
189                .send()
190                .await?
191        };
192
193        let response_json: ApiResponse = response.json().await?;
194
195        if !response_json.ok {
196            let error_code = response_json.error.as_deref().unwrap_or("Unknown error");
197
198            // Display error guidance if available
199            if let Some(guidance) = format_error_guidance(error_code) {
200                eprintln!("{}", guidance);
201            }
202
203            return Err(ApiError::SlackError(error_code.to_string()));
204        }
205
206        Ok(response_json)
207    }
208
209    /// Make an API call with automatic retry logic (for generic API calls)
210    pub async fn call(
211        &self,
212        method: Method,
213        endpoint: &str,
214        token: &str,
215        body: RequestBody,
216    ) -> Result<Response> {
217        let url = format!("{}/{}", self.config.base_url, endpoint);
218        let mut attempt = 0;
219
220        loop {
221            let response = self.execute_request(&url, &method, token, &body).await?;
222
223            // Check for rate limiting
224            if response.status() == StatusCode::TOO_MANY_REQUESTS {
225                // Extract Retry-After header
226                let retry_after = self.extract_retry_after(&response);
227
228                if attempt >= self.config.max_retries {
229                    return Err(ApiClientError::RateLimitExceeded(retry_after));
230                }
231
232                // Wait for the specified duration
233                tokio::time::sleep(Duration::from_secs(retry_after)).await;
234                attempt += 1;
235                continue;
236            }
237
238            // For other errors, apply exponential backoff
239            if !response.status().is_success() && attempt < self.config.max_retries {
240                let backoff = self.calculate_backoff(attempt);
241                tokio::time::sleep(backoff).await;
242                attempt += 1;
243                continue;
244            }
245
246            return Ok(response);
247        }
248    }
249
250    /// Execute a single HTTP request
251    async fn execute_request(
252        &self,
253        url: &str,
254        method: &Method,
255        token: &str,
256        body: &RequestBody,
257    ) -> Result<Response> {
258        let mut request = self.client.request(method.clone(), url);
259
260        // Add authorization header
261        request = request.header("Authorization", format!("Bearer {}", token));
262
263        // Add body based on type
264        match body {
265            RequestBody::Form(params) => {
266                request = request
267                    .header("Content-Type", "application/x-www-form-urlencoded")
268                    .form(params);
269            }
270            RequestBody::Json(json) => {
271                request = request
272                    .header("Content-Type", "application/json")
273                    .json(json);
274            }
275            RequestBody::None => {}
276        }
277
278        let response = request.send().await?;
279        Ok(response)
280    }
281
282    /// Extract Retry-After header value
283    fn extract_retry_after(&self, response: &Response) -> u64 {
284        response
285            .headers()
286            .get("Retry-After")
287            .and_then(|v| v.to_str().ok())
288            .and_then(|s| s.parse::<u64>().ok())
289            .unwrap_or(60) // Default to 60 seconds if not specified
290    }
291
292    /// Calculate exponential backoff with jitter
293    fn calculate_backoff(&self, attempt: u32) -> Duration {
294        let base = self.config.initial_backoff_ms;
295        let max = self.config.max_backoff_ms;
296
297        // Exponential backoff: base * 2^attempt
298        let backoff = base * 2_u64.pow(attempt);
299        let backoff = backoff.min(max);
300
301        // Add jitter (±25%)
302        let jitter = (backoff as f64 * 0.25) as u64;
303        let jitter = rand::random::<u64>() % (jitter * 2 + 1);
304        let backoff = backoff
305            .saturating_sub(jitter / 2)
306            .saturating_add(jitter / 2);
307
308        Duration::from_millis(backoff)
309    }
310}
311
312impl Default for ApiClient {
313    fn default() -> Self {
314        Self::new()
315    }
316}
317
318/// Request body type
319#[derive(Debug, Clone)]
320pub enum RequestBody {
321    Form(Vec<(String, String)>),
322    Json(Value),
323    None,
324}
325
326#[cfg(test)]
327mod tests {
328    use super::*;
329
330    #[test]
331    fn test_api_method_as_str() {
332        assert_eq!(ApiMethod::SearchMessages.as_str(), "search.messages");
333        assert_eq!(ApiMethod::ConversationsList.as_str(), "conversations.list");
334        assert_eq!(
335            ApiMethod::ConversationsHistory.as_str(),
336            "conversations.history"
337        );
338        assert_eq!(ApiMethod::UsersInfo.as_str(), "users.info");
339        assert_eq!(ApiMethod::ChatPostMessage.as_str(), "chat.postMessage");
340        assert_eq!(ApiMethod::ChatUpdate.as_str(), "chat.update");
341        assert_eq!(ApiMethod::ChatDelete.as_str(), "chat.delete");
342        assert_eq!(ApiMethod::ReactionsAdd.as_str(), "reactions.add");
343        assert_eq!(ApiMethod::ReactionsRemove.as_str(), "reactions.remove");
344    }
345
346    #[test]
347    fn test_api_method_is_write() {
348        assert!(!ApiMethod::SearchMessages.is_write());
349        assert!(!ApiMethod::ConversationsList.is_write());
350        assert!(!ApiMethod::ConversationsHistory.is_write());
351        assert!(!ApiMethod::UsersInfo.is_write());
352        assert!(ApiMethod::ChatPostMessage.is_write());
353        assert!(ApiMethod::ChatUpdate.is_write());
354        assert!(ApiMethod::ChatDelete.is_write());
355        assert!(ApiMethod::ReactionsAdd.is_write());
356        assert!(ApiMethod::ReactionsRemove.is_write());
357    }
358
359    #[test]
360    fn test_api_method_is_destructive() {
361        assert!(!ApiMethod::SearchMessages.is_destructive());
362        assert!(!ApiMethod::ConversationsList.is_destructive());
363        assert!(!ApiMethod::ConversationsHistory.is_destructive());
364        assert!(!ApiMethod::UsersInfo.is_destructive());
365        assert!(!ApiMethod::ChatPostMessage.is_destructive());
366        assert!(ApiMethod::ChatUpdate.is_destructive());
367        assert!(ApiMethod::ChatDelete.is_destructive());
368        assert!(!ApiMethod::ReactionsAdd.is_destructive());
369        assert!(ApiMethod::ReactionsRemove.is_destructive());
370    }
371
372    #[test]
373    fn test_api_method_uses_get() {
374        // GET methods
375        assert!(ApiMethod::SearchMessages.uses_get_method());
376        assert!(ApiMethod::ConversationsList.uses_get_method());
377        assert!(ApiMethod::ConversationsHistory.uses_get_method());
378        assert!(ApiMethod::UsersInfo.uses_get_method());
379        assert!(ApiMethod::UsersList.uses_get_method());
380
381        // POST methods
382        assert!(!ApiMethod::ChatPostMessage.uses_get_method());
383        assert!(!ApiMethod::ChatUpdate.uses_get_method());
384        assert!(!ApiMethod::ChatDelete.uses_get_method());
385        assert!(!ApiMethod::ReactionsAdd.uses_get_method());
386        assert!(!ApiMethod::ReactionsRemove.uses_get_method());
387    }
388
389    #[test]
390    fn test_api_client_config_default() {
391        let config = ApiClientConfig::default();
392        assert_eq!(config.base_url, "https://slack.com/api");
393        assert_eq!(config.max_retries, 3);
394        assert_eq!(config.initial_backoff_ms, 1000);
395        assert_eq!(config.max_backoff_ms, 32000);
396    }
397
398    #[test]
399    fn test_api_client_creation() {
400        let client = ApiClient::new();
401        assert_eq!(client.base_url(), "https://slack.com/api");
402    }
403
404    #[test]
405    fn test_api_client_custom_config() {
406        let config = ApiClientConfig {
407            base_url: "https://test.example.com".to_string(),
408            max_retries: 5,
409            initial_backoff_ms: 500,
410            max_backoff_ms: 10000,
411        };
412
413        let client = ApiClient::with_config(config.clone());
414        assert_eq!(client.base_url(), "https://test.example.com");
415        assert_eq!(client.config.max_retries, 5);
416    }
417}
slack_rs/api/client.rs

slack_rs/api/
client.rs
