tushare_api/
client.rs

1use reqwest::Client;
2use std::time::{Duration, Instant};
3use std::collections::HashMap;
4use crate::error::{TushareError, TushareResult};
5use crate::types::{TushareRequest, TushareResponse, TushareEntityList};
6use crate::api::{Api, serialize_api_name};
7use crate::logging::{LogConfig, LogLevel, Logger};
8use serde::{Serialize};
9use serde_json;
10use std::time::{SystemTime, UNIX_EPOCH};
11
12/// HTTP client configuration for reqwest::Client
13#[derive(Debug, Clone)]
14pub struct HttpClientConfig {
15    /// Connection timeout duration
16    pub connect_timeout: Duration,
17    /// Request timeout duration
18    pub timeout: Duration,
19    /// Maximum idle connections per host
20    pub pool_max_idle_per_host: usize,
21    /// Pool idle timeout duration
22    pub pool_idle_timeout: Duration,
23    /// User agent string
24    pub user_agent: Option<String>,
25    /// Enable TCP_NODELAY to reduce latency
26    pub tcp_nodelay: bool,
27    /// TCP keep-alive duration
28    pub tcp_keepalive: Option<Duration>,
29}
30
31impl Default for HttpClientConfig {
32    fn default() -> Self {
33        Self {
34            connect_timeout: Duration::from_secs(10),
35            timeout: Duration::from_secs(30),
36            pool_max_idle_per_host: 20,  // Increased for better performance
37            pool_idle_timeout: Duration::from_secs(90),  // Longer idle timeout
38            user_agent: Some("tushare-api-rust/1.0.0".to_string()),
39            tcp_nodelay: true,  // Reduce latency
40            tcp_keepalive: Some(Duration::from_secs(60)),  // Keep connections alive
41        }
42    }
43}
44
45impl HttpClientConfig {
46    /// Create a new HTTP client configuration with default values
47    pub fn new() -> Self {
48        Self::default()
49    }
50    
51    /// Set connection timeout
52    pub fn with_connect_timeout(mut self, timeout: Duration) -> Self {
53        self.connect_timeout = timeout;
54        self
55    }
56    
57    /// Set request timeout
58    pub fn with_timeout(mut self, timeout: Duration) -> Self {
59        self.timeout = timeout;
60        self
61    }
62    
63    /// Set maximum idle connections per host
64    pub fn with_pool_max_idle_per_host(mut self, max_idle: usize) -> Self {
65        self.pool_max_idle_per_host = max_idle;
66        self
67    }
68    
69    /// Set pool idle timeout
70    pub fn with_pool_idle_timeout(mut self, timeout: Duration) -> Self {
71        self.pool_idle_timeout = timeout;
72        self
73    }
74    
75    /// Set user agent string
76    pub fn with_user_agent<S: Into<String>>(mut self, user_agent: S) -> Self {
77        self.user_agent = Some(user_agent.into());
78        self
79    }
80    
81    /// Enable or disable TCP_NODELAY
82    pub fn with_tcp_nodelay(mut self, enabled: bool) -> Self {
83        self.tcp_nodelay = enabled;
84        self
85    }
86    
87    /// Set TCP keep-alive duration
88    pub fn with_tcp_keepalive(mut self, duration: Option<Duration>) -> Self {
89        self.tcp_keepalive = duration;
90        self
91    }
92    
93    /// Build reqwest::Client with this configuration
94    pub(crate) fn build_client(&self) -> Result<Client, reqwest::Error> {
95        let mut builder = Client::builder()
96            .connect_timeout(self.connect_timeout)
97            .timeout(self.timeout)
98            .pool_max_idle_per_host(self.pool_max_idle_per_host)
99            .pool_idle_timeout(self.pool_idle_timeout)
100            .tcp_nodelay(self.tcp_nodelay);
101            
102        if let Some(ref user_agent) = self.user_agent {
103            builder = builder.user_agent(user_agent);
104        }
105        
106        if let Some(keepalive) = self.tcp_keepalive {
107            builder = builder.tcp_keepalive(keepalive);
108        }
109        
110        builder.build()
111    }
112}
113
114/// Internal request structure with token included
115#[derive(Debug, Serialize)]
116struct InternalTushareRequest {
117    #[serde(serialize_with = "serialize_api_name")]
118    api_name: Api,
119    token: String,
120    params: HashMap<String, String>,
121    fields: Vec<String>,
122}
123
124/// Tushare API client
125#[derive(Debug)]
126pub struct TushareClient {
127    token: String,
128    client: Client,
129    logger: Logger,
130}
131
132/// Tushare client builder
133#[derive(Debug)]
134pub struct TushareClientBuilder {
135    token: Option<String>,
136    http_config: HttpClientConfig,
137    log_config: LogConfig,
138}
139
140impl TushareClientBuilder {
141    pub fn new() -> Self {
142        Self {
143            token: None,
144            http_config: HttpClientConfig::default(),
145            log_config: LogConfig::default(),
146        }
147    }
148
149    pub fn with_token(mut self, token: &str) -> Self {
150        self.token = Some(token.to_string());
151        self
152    }
153
154    pub fn with_connect_timeout(mut self, connect_timeout: Duration) -> Self {
155        self.http_config = self.http_config.with_connect_timeout(connect_timeout);
156        self
157    }
158
159    pub fn with_timeout(mut self, timeout: Duration) -> Self {
160        self.http_config = self.http_config.with_timeout(timeout);
161        self
162    }
163    
164    /// Set HTTP client configuration
165    pub fn with_http_config(mut self, http_config: HttpClientConfig) -> Self {
166        self.http_config = http_config;
167        self
168    }
169    
170    /// Set maximum idle connections per host
171    pub fn with_pool_max_idle_per_host(mut self, max_idle: usize) -> Self {
172        self.http_config = self.http_config.with_pool_max_idle_per_host(max_idle);
173        self
174    }
175    
176    /// Set pool idle timeout
177    pub fn with_pool_idle_timeout(mut self, timeout: Duration) -> Self {
178        self.http_config = self.http_config.with_pool_idle_timeout(timeout);
179        self
180    }
181
182    pub fn with_log_config(mut self, log_config: LogConfig) -> Self {
183        self.log_config = log_config;
184        self
185    }
186
187    /// Set log level
188    pub fn with_log_level(mut self, level: LogLevel) -> Self {
189        self.log_config.level = level;
190        self
191    }
192
193    /// Enable or disable request logging
194    pub fn log_requests(mut self, enabled: bool) -> Self {
195        self.log_config.log_requests = enabled;
196        self
197    }
198
199    /// Enable or disable response logging
200    pub fn log_responses(mut self, enabled: bool) -> Self {
201        self.log_config.log_responses = enabled;
202        self
203    }
204
205    /// Enable or disable sensitive data logging
206    pub fn log_sensitive_data(mut self, enabled: bool) -> Self {
207        self.log_config.log_sensitive_data = enabled;
208        self
209    }
210
211    /// Enable or disable performance metrics logging
212    pub fn log_performance(mut self, enabled: bool) -> Self {
213        self.log_config.log_performance = enabled;
214        self
215    }
216
217    pub fn build(self) -> TushareResult<TushareClient> {
218        let token = self.token.ok_or(TushareError::InvalidToken)?;
219        
220        let client = self.http_config.build_client()
221            .map_err(TushareError::HttpError)?;
222
223        Ok(TushareClient {
224            token,
225            client,
226            logger: Logger::new(self.log_config),
227        })
228    }
229}
230
231impl TushareClient {
232    /// Create client builder
233    pub fn builder() -> TushareClientBuilder {
234        TushareClientBuilder::new()
235    }
236
237
238
239    /// Create a new Tushare client with default timeout settings
240    /// 
241    /// # Arguments
242    /// 
243    /// * `token` - Tushare API Token
244    /// 
245    /// # Example
246    /// 
247    /// ```rust
248    /// use tushare_api::TushareClient;
249    /// 
250    /// let client = TushareClient::new("your_token_here");
251    /// ```
252    pub fn new(token: &str) -> Self {
253        Self::with_timeout(token, Duration::from_secs(10), Duration::from_secs(30))
254    }
255
256    /// Create a new Tushare client from TUSHARE_TOKEN environment variable with default timeout settings
257    /// 
258    /// # Errors
259    /// 
260    /// Returns `TushareError::InvalidToken` if TUSHARE_TOKEN environment variable does not exist or is empty
261    /// 
262    /// # Example
263    /// 
264    /// ```rust,no_run
265    /// use tushare_api::{TushareClient, TushareResult};
266    /// 
267    /// // Requires TUSHARE_TOKEN environment variable to be set
268    /// let client = TushareClient::from_env()?;
269    /// # Ok::<(), tushare_api::TushareError>(())
270    /// ```
271    pub fn from_env() -> TushareResult<Self> {
272        let token = std::env::var("TUSHARE_TOKEN")
273            .map_err(|_| TushareError::InvalidToken)?
274            .trim()
275            .to_string();
276        
277        if token.is_empty() {
278            return Err(TushareError::InvalidToken);
279        }
280        
281        Ok(Self::new(&token))
282    }
283
284    /// Create a new Tushare client from TUSHARE_TOKEN environment variable with custom timeout settings
285    /// 
286    /// # Arguments
287    /// 
288    /// * `connect_timeout` - Connection timeout duration
289    /// * `timeout` - Request timeout duration
290    /// 
291    /// # Errors
292    /// 
293    /// Returns `TushareError::InvalidToken` if TUSHARE_TOKEN environment variable does not exist or is empty
294    /// 
295    /// # Example
296    /// 
297    /// ```rust,no_run
298    /// use tushare_api::{TushareClient, TushareResult};
299    /// use std::time::Duration;
300    /// 
301    /// // Requires TUSHARE_TOKEN environment variable to be set
302    /// let client = TushareClient::from_env_with_timeout(
303    ///     Duration::from_secs(5),  // Connection timeout 5 seconds
304    ///     Duration::from_secs(60)  // Request timeout 60 seconds
305    /// )?;
306    /// # Ok::<(), tushare_api::TushareError>(())
307    /// ```
308    pub fn from_env_with_timeout(connect_timeout: Duration, timeout: Duration) -> TushareResult<Self> {
309        let token = std::env::var("TUSHARE_TOKEN")
310            .map_err(|_| TushareError::InvalidToken)?
311            .trim()
312            .to_string();
313        
314        if token.is_empty() {
315            return Err(TushareError::InvalidToken);
316        }
317        
318        Ok(Self::with_timeout(&token, connect_timeout, timeout))
319    }
320
321    /// Create a new Tushare client with custom timeout settings
322    /// 
323    /// # Arguments
324    /// 
325    /// * `token` - Tushare API Token
326    /// * `connect_timeout` - Connection timeout duration
327    /// * `timeout` - Request timeout duration
328    /// 
329    /// # Example
330    /// 
331    /// ```rust
332    /// use tushare_api::TushareClient;
333    /// use std::time::Duration;
334    /// 
335    /// let client = TushareClient::with_timeout(
336    ///     "your_token_here",
337    ///     Duration::from_secs(5),  // Connection timeout 5 seconds
338    ///     Duration::from_secs(60)  // Request timeout 60 seconds
339    /// );
340    /// ```
341    pub fn with_timeout(token: &str, connect_timeout: Duration, timeout: Duration) -> Self {
342        let http_config = HttpClientConfig::new()
343            .with_connect_timeout(connect_timeout)
344            .with_timeout(timeout);
345            
346        let client = http_config.build_client()
347            .expect("Failed to create HTTP client");
348
349        TushareClient {
350            token: token.to_string(),
351            client,
352            logger: Logger::new(LogConfig::default()),
353        }
354    }
355
356    /// Call Tushare API with flexible string types support
357    /// 
358    /// # Arguments
359    /// 
360    /// * `request` - API request parameters, supports direct use of string literals
361    /// 
362    /// # Returns
363    /// 
364    /// Returns API response result
365    /// 
366    /// # Example
367    /// 
368    /// ```rust
369    /// use tushare_api::{TushareClient, TushareRequest, Api, params, fields, request};
370    /// 
371    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
372    ///     let client = TushareClient::new("your_token_here");
373    ///     
374    ///     // Now you can use string literals directly!
375    ///     let request = request!(Api::StockBasic, {
376    ///         "list_status" => "L"
377    ///     }, [
378    ///         "ts_code", "name"
379    ///     ]);
380    ///     
381    ///     let response = client.call_api(request).await?;
382    ///     println!("Response: {:?}", response);
383    /// #   Ok(())
384    /// # }
385    /// ```
386    pub async fn call_api(&self, request: TushareRequest) -> TushareResult<TushareResponse> {
387        let request_id = generate_request_id();
388        let start_time = Instant::now();
389        
390        // Log API call start
391        self.logger.log_api_start(
392            &request_id,
393            &request.api_name.name(),
394            request.params.len(),
395            request.fields.len()
396        );
397        
398        // Log detailed request information (if enabled)
399        let token_preview_string = if self.logger.config().log_sensitive_data {
400            Some(format!("token: {}***", &self.token[..self.token.len().min(8)]))
401        } else {
402            None
403        };
404        
405        self.logger.log_request_details(
406            &request_id,
407            &request.api_name.name(),
408            &format!("{:?}", request.params),
409            &format!("{:?}", request.fields),
410            token_preview_string.as_deref()
411        );
412        
413        let internal_request = InternalTushareRequest {
414            api_name: request.api_name,
415            token: self.token.clone(),
416            params: request.params,
417            fields: request.fields,
418        };
419
420        self.logger.log_http_request(&request_id);
421        
422        let response = self.client
423            .post("http://api.tushare.pro")
424            .json(&internal_request)
425            .send()
426            .await
427            .map_err(|e| {
428                let elapsed = start_time.elapsed();
429                self.logger.log_http_error(&request_id, elapsed, &e.to_string());
430                e
431            })?;
432
433        let status = response.status();
434        self.logger.log_http_response(&request_id, status.as_u16());
435        
436        let response_text = response.text().await
437            .map_err(|e| {
438                let elapsed = start_time.elapsed();
439                self.logger.log_response_read_error(&request_id, elapsed, &e.to_string());
440                e
441            })?;
442        
443        self.logger.log_raw_response(&request_id, &response_text);
444        
445        let tushare_response: TushareResponse = serde_json::from_str(&response_text)
446            .map_err(|e| {
447                let elapsed = start_time.elapsed();
448                self.logger.log_json_parse_error(&request_id, elapsed, &e.to_string(), &response_text);
449                e
450            })?;
451
452        let elapsed = start_time.elapsed();
453        
454        if tushare_response.code != 0 {
455            let message = format!("error code: {}, error msg: {}", tushare_response.code, tushare_response.msg.clone().unwrap_or_default());
456            self.logger.log_api_error(&request_id, elapsed, tushare_response.code, &message);
457            return Err(TushareError::ApiError {
458                code: tushare_response.code,
459                message
460            });
461        }
462
463        // Log success information and performance metrics
464        self.logger.log_api_success(&request_id, elapsed, tushare_response.data.clone().map(|data| data.items.len()).unwrap_or(0));
465        
466        // Log response details (if enabled)
467        self.logger.log_response_details(
468            &request_id,
469            &tushare_response.request_id,
470            &format!("{:?}", tushare_response.data.as_ref().map(|d| &d.fields))
471        );
472
473        Ok(tushare_response)
474    }
475
476    /// Call Tushare API with automatic type conversion to `TushareEntityList<T>`
477    /// 
478    /// This method provides a clean, type-safe way to get paginated API responses.
479    /// You specify the entity type T, and get back a `TushareEntityList<T>` with
480    /// built-in pagination metadata.
481    /// 
482    /// # Type Parameters
483    /// 
484    /// * `T` - The entity type that implements `FromTushareData`
485    /// 
486    /// # Arguments
487    /// 
488    /// * `request` - API request parameters
489    /// 
490    /// # Returns
491    /// 
492    /// Returns a `TushareEntityList<T>` containing:
493    /// - `items: Vec<T>` - The converted data items
494    /// - `has_more: bool` - Whether more pages are available
495    /// - `count: i64` - Total number of records across all pages
496    /// 
497    /// # Example
498    /// 
499    /// ```rust
500    /// use tushare_api::{TushareClient, Api, request, TushareEntityList, params, fields, TushareRequest, DeriveFromTushareData};
501
502    /// #[derive(Debug, Clone, DeriveFromTushareData)]
503    /// pub struct Stock {
504    ///     pub ts_code: String,
505    ///     pub name: String,
506    ///     pub area: Option<String>,
507    /// }
508    /// 
509    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
510    ///     let client = TushareClient::from_env()?;
511    ///     
512    ///     // Clean, intuitive API call
513    ///     let stocks: TushareEntityList<Stock> = client.call_api_as(request!(
514    ///         Api::StockBasic, {
515    ///             "list_status" => "L",
516    ///             "limit" => "100"
517    ///         }, [
518    ///             "ts_code", "name", "area"
519    ///         ]
520    ///     )).await?;
521    ///     
522    ///     // Access pagination info
523    ///     println!("Current page: {} stocks", stocks.len());
524    ///     println!("Total available: {} stocks", stocks.count());
525    ///     println!("Has more pages: {}", stocks.has_more());
526    ///     
527    ///     // Iterate over items
528    ///     for stock in &stocks {
529    ///         println!("{}: {} ({})", 
530    ///                  stock.ts_code, 
531    ///                  stock.name, 
532    ///                  stock.area.as_deref().unwrap_or("Unknown"));
533    ///     }
534    /// #   Ok(())
535    /// # }
536    /// ```
537    pub async fn call_api_as<T>(&self, request: TushareRequest) -> TushareResult<TushareEntityList<T>>
538    where
539        T: crate::traits::FromTushareData,
540    {
541        let response = self.call_api(request).await?;
542        TushareEntityList::try_from(response).map_err(Into::into)
543    }
544}
545
546/// Generate a unique request ID for logging purposes
547fn generate_request_id() -> String {
548    let timestamp = SystemTime::now()
549        .duration_since(UNIX_EPOCH)
550        .unwrap_or_default()
551        .as_nanos();
552    format!("req_{}", timestamp)
553}
tushare_api/client.rs

tushare_api/
client.rs
