runpod_sdk/client/
config.rs

1//! RunPod client configuration and builder.
2//!
3//! This module provides the configuration types and builder pattern for creating
4//! and customizing [`RunpodClient`] instances.
5
6use std::fmt;
7use std::time::Duration;
8
9use derive_builder::Builder;
10use reqwest::Client;
11
12use crate::Result;
13#[cfg(feature = "tracing")]
14use crate::TRACING_TARGET_CONFIG;
15use crate::client::RunpodClient;
16
17/// Configuration for the Runpod API client.
18///
19/// This struct holds all the necessary configuration parameters for creating and using
20/// a Runpod API client, including authentication credentials, API endpoint information,
21/// and HTTP client settings.
22///
23/// # Examples
24///
25/// Creating a config with defaults:
26/// ```no_run
27/// # use runpod_sdk::RunpodConfig;
28/// let config = RunpodConfig::builder()
29///     .with_api_key("your-api-key")
30///     .build()
31///     .unwrap();
32/// ```
33///
34/// Creating a config from environment:
35/// ```no_run
36/// # use runpod_sdk::RunpodConfig;
37/// // Requires RUNPOD_API_KEY environment variable
38/// let config = RunpodConfig::from_env().unwrap();
39/// ```
40///
41/// Custom configuration:
42/// ```no_run
43/// # use runpod_sdk::RunpodConfig;
44/// # use std::time::Duration;
45/// let config = RunpodConfig::builder()
46///     .with_api_key("your-api-key")
47///     .with_rest_url("https://custom.api.com")
48///     .with_timeout(Duration::from_secs(60))
49///     .build()
50///     .unwrap();
51/// ```
52#[derive(Clone, Builder)]
53#[builder(
54    name = "RunpodBuilder",
55    pattern = "owned",
56    setter(into, strip_option, prefix = "with"),
57    build_fn(validate = "Self::validate_config")
58)]
59pub struct RunpodConfig {
60    /// API key for authentication with the Runpod API.
61    ///
62    /// You can obtain your API key from the Runpod dashboard.
63    api_key: String,
64
65    /// Base REST URL for the Runpod API.
66    ///
67    /// Defaults to the official Runpod REST API endpoint.
68    #[builder(default = "Self::default_rest_url()")]
69    rest_url: String,
70
71    /// Base API URL for the Runpod serverless endpoints.
72    ///
73    /// Defaults to the official Runpod API endpoint.
74    #[cfg(feature = "serverless")]
75    #[cfg_attr(docsrs, doc(cfg(feature = "serverless")))]
76    #[builder(default = "Self::default_api_url()")]
77    api_url: String,
78
79    /// Timeout for HTTP requests.
80    ///
81    /// Controls how long the client will wait for API responses before timing out.
82    #[builder(default = "Self::default_timeout()")]
83    timeout: Duration,
84
85    /// Optional custom reqwest client.
86    ///
87    /// If provided, this client will be used instead of creating a new one.
88    /// This allows for custom configuration of the HTTP client (e.g., proxies, custom headers, etc.).
89    #[builder(default = "None")]
90    client: Option<Client>,
91}
92
93impl RunpodBuilder {
94    /// Returns the default REST URL for the Runpod API.
95    fn default_rest_url() -> String {
96        "https://rest.runpod.io/v1".to_string()
97    }
98
99    /// Returns the default API URL for the Runpod serverless endpoints.
100    #[cfg(feature = "serverless")]
101    #[cfg_attr(docsrs, doc(cfg(feature = "serverless")))]
102    fn default_api_url() -> String {
103        "https://api.runpod.io/v2".to_string()
104    }
105
106    /// Returns the default timeout.
107    fn default_timeout() -> Duration {
108        Duration::from_secs(30)
109    }
110
111    /// Validates the configuration before building.
112    fn validate_config(&self) -> Result<(), String> {
113        // Validate API key is not empty
114        if let Some(ref api_key) = self.api_key
115            && api_key.trim().is_empty()
116        {
117            return Err("API key cannot be empty".to_string());
118        }
119
120        // Validate timeout is reasonable
121        if let Some(timeout) = self.timeout {
122            if timeout.is_zero() {
123                return Err("Timeout must be greater than 0".to_string());
124            }
125            if timeout > Duration::from_secs(300) {
126                return Err("Timeout cannot exceed 300 seconds (5 minutes)".to_string());
127            }
128        }
129
130        Ok(())
131    }
132
133    /// Creates a RunPod API client directly from the builder.
134    ///
135    /// This is a convenience method that builds the configuration and
136    /// creates a client in one step. This is the recommended way to
137    /// create a client.
138    ///
139    /// # Examples
140    ///
141    /// ```no_run
142    /// # use runpod_sdk::RunpodConfig;
143    /// let client = RunpodConfig::builder()
144    ///     .with_api_key("your-api-key")
145    ///     .build_client()
146    ///     .unwrap();
147    /// ```
148    pub fn build_client(self) -> Result<RunpodClient> {
149        let config = self.build()?;
150        RunpodClient::new(config)
151    }
152}
153
154impl RunpodConfig {
155    /// Creates a new configuration builder.
156    ///
157    /// This is the recommended way to construct a `RunpodConfig`.
158    ///
159    /// # Examples
160    ///
161    /// ```no_run
162    /// # use runpod_sdk::RunpodConfig;
163    /// let config = RunpodConfig::builder()
164    ///     .with_api_key("your-api-key")
165    ///     .build()
166    ///     .unwrap();
167    /// ```
168    pub fn builder() -> RunpodBuilder {
169        RunpodBuilder::default()
170    }
171
172    /// Creates a new RunPod API client using this configuration.
173    ///
174    /// # Examples
175    ///
176    /// ```no_run
177    /// # use runpod_sdk::RunpodConfig;
178    /// let config = RunpodConfig::builder()
179    ///     .with_api_key("your-api-key")
180    ///     .build()
181    ///     .unwrap();
182    ///
183    /// let client = config.build_client().unwrap();
184    /// ```
185    pub fn build_client(self) -> Result<RunpodClient> {
186        RunpodClient::new(self)
187    }
188
189    /// Returns the API key.
190    pub fn api_key(&self) -> &str {
191        &self.api_key
192    }
193
194    /// Returns a masked version of the API key for safe display/logging.
195    ///
196    /// Shows the first 4 characters followed by "****", or just "****"
197    /// if the key is shorter than 4 characters.
198    pub fn masked_api_key(&self) -> String {
199        if self.api_key.len() > 4 {
200            format!("{}****", &self.api_key[..4])
201        } else {
202            "****".to_string()
203        }
204    }
205
206    /// Returns the base REST URL.
207    pub fn rest_url(&self) -> &str {
208        &self.rest_url
209    }
210
211    /// Returns the API URL for serverless endpoints.
212    #[cfg(feature = "serverless")]
213    #[cfg_attr(docsrs, doc(cfg(feature = "serverless")))]
214    pub fn api_url(&self) -> &str {
215        &self.api_url
216    }
217
218    /// Returns the timeout duration.
219    pub fn timeout(&self) -> Duration {
220        self.timeout
221    }
222
223    /// Returns a clone of the custom reqwest client, if one was provided.
224    pub(crate) fn client(&self) -> Option<Client> {
225        self.client.clone()
226    }
227
228    /// Creates a configuration from environment variables.
229    ///
230    /// Reads the API key from the `RUNPOD_API_KEY` environment variable.
231    /// Optionally reads `RUNPOD_REST_URL`, `RUNPOD_API_URL` (with serverless feature),
232    /// and `RUNPOD_TIMEOUT_SECS` if set.
233    ///
234    /// # Errors
235    ///
236    /// Returns an error if:
237    /// - The `RUNPOD_API_KEY` environment variable is not set
238    /// - Any environment variable contains an invalid value
239    ///
240    /// # Examples
241    ///
242    /// ```no_run
243    /// # use runpod_sdk::RunpodConfig;
244    /// // Set environment variable first:
245    /// // export RUNPOD_API_KEY=your-api-key
246    /// let config = RunpodConfig::from_env().unwrap();
247    /// ```
248    #[cfg_attr(feature = "tracing", tracing::instrument)]
249    pub fn from_env() -> Result<Self> {
250        #[cfg(feature = "tracing")]
251        tracing::debug!(target: TRACING_TARGET_CONFIG, "Loading configuration from environment");
252
253        let api_key = std::env::var("RUNPOD_API_KEY").map_err(|_| {
254            #[cfg(feature = "tracing")]
255            tracing::error!(target: TRACING_TARGET_CONFIG, "RUNPOD_API_KEY environment variable not set");
256
257            RunpodBuilderError::ValidationError(
258                "RUNPOD_API_KEY environment variable not set".to_string(),
259            )
260        })?;
261
262        let mut builder = Self::builder().with_api_key(api_key);
263
264        // Optional: custom REST URL (also support legacy RUNPOD_BASE_URL)
265        if let Ok(rest_url) = std::env::var("RUNPOD_REST_URL") {
266            #[cfg(feature = "tracing")]
267            tracing::debug!(target: TRACING_TARGET_CONFIG, rest_url = %rest_url, "Using custom REST URL");
268
269            builder = builder.with_rest_url(rest_url);
270        } else if let Ok(base_url) = std::env::var("RUNPOD_BASE_URL") {
271            #[cfg(feature = "tracing")]
272            tracing::debug!(target: TRACING_TARGET_CONFIG, base_url = %base_url, "Using custom base URL (legacy)");
273
274            builder = builder.with_rest_url(base_url);
275        }
276
277        // Optional: custom API URL for serverless endpoints
278        #[cfg(feature = "serverless")]
279        if let Ok(api_url) = std::env::var("RUNPOD_API_URL") {
280            #[cfg(feature = "tracing")]
281            tracing::debug!(
282                target: TRACING_TARGET_CONFIG,
283                api_url = %api_url,
284                "Using custom API URL"
285            );
286
287            builder = builder.with_api_url(api_url);
288        }
289
290        // Optional: custom timeout
291        if let Ok(timeout_str) = std::env::var("RUNPOD_TIMEOUT_SECS") {
292            let timeout_secs = timeout_str.parse::<u64>().map_err(|_| {
293                #[cfg(feature = "tracing")]
294                tracing::error!(target: TRACING_TARGET_CONFIG, timeout_str = %timeout_str, "Invalid RUNPOD_TIMEOUT_SECS value");
295
296                RunpodBuilderError::ValidationError(format!(
297                    "Invalid RUNPOD_TIMEOUT_SECS value: {}",
298                    timeout_str
299                ))
300            })?;
301
302            #[cfg(feature = "tracing")]
303            tracing::debug!(target: TRACING_TARGET_CONFIG, timeout_secs, "Using custom timeout");
304
305            builder = builder.with_timeout(Duration::from_secs(timeout_secs));
306        }
307
308        let config = builder.build()?;
309
310        #[cfg(feature = "tracing")]
311        tracing::info!(target: TRACING_TARGET_CONFIG,
312            rest_url = %config.rest_url(),
313            timeout = ?config.timeout(),
314            "Configuration loaded successfully from environment"
315        );
316
317        Ok(config)
318    }
319}
320
321impl fmt::Debug for RunpodConfig {
322    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
323        let mut debug_struct = f.debug_struct("RunpodConfig");
324        debug_struct
325            .field("api_key", &self.masked_api_key())
326            .field("rest_url", &self.rest_url)
327            .field("timeout", &self.timeout);
328
329        #[cfg(feature = "serverless")]
330        debug_struct.field("api_url", &self.api_url);
331        debug_struct.finish()
332    }
333}
334
335#[cfg(test)]
336mod tests {
337    use super::*;
338
339    #[test]
340    fn test_config_builder() -> Result<()> {
341        let config = RunpodConfig::builder().with_api_key("test_key").build()?;
342
343        assert_eq!(config.api_key(), "test_key");
344        assert_eq!(config.rest_url(), "https://rest.runpod.io/v1");
345        #[cfg(feature = "serverless")]
346        assert_eq!(config.api_url(), "https://api.runpod.io/v2");
347        assert_eq!(config.timeout(), Duration::from_secs(30));
348
349        Ok(())
350    }
351
352    #[test]
353    fn test_config_builder_with_custom_values() -> Result<()> {
354        let config = RunpodConfig::builder()
355            .with_api_key("test_key")
356            .with_rest_url("https://custom.api.com")
357            .with_timeout(Duration::from_secs(60))
358            .build()?;
359
360        assert_eq!(config.api_key(), "test_key");
361        assert_eq!(config.rest_url(), "https://custom.api.com");
362        assert_eq!(config.timeout(), Duration::from_secs(60));
363
364        Ok(())
365    }
366
367    #[test]
368    fn test_config_validation_empty_api_key() {
369        let result = RunpodConfig::builder().with_api_key("").build();
370        assert!(result.is_err());
371    }
372
373    #[test]
374    fn test_config_validation_zero_timeout() {
375        let result = RunpodConfig::builder()
376            .with_api_key("test_key")
377            .with_timeout(Duration::from_secs(0))
378            .build();
379
380        assert!(result.is_err());
381    }
382
383    #[test]
384    fn test_config_validation_excessive_timeout() {
385        let result = RunpodConfig::builder()
386            .with_api_key("test_key")
387            .with_timeout(Duration::from_secs(400))
388            .build();
389
390        assert!(result.is_err());
391    }
392
393    #[test]
394    fn test_config_builder_with_all_options() -> Result<()> {
395        let config = RunpodConfig::builder()
396            .with_api_key("test_key_comprehensive")
397            .with_rest_url("https://api.custom-domain.com/v2")
398            .with_timeout(Duration::from_secs(120))
399            .build()?;
400
401        assert_eq!(config.api_key(), "test_key_comprehensive");
402        assert_eq!(config.rest_url(), "https://api.custom-domain.com/v2");
403        assert_eq!(config.timeout(), Duration::from_secs(120));
404
405        Ok(())
406    }
407
408    #[test]
409    fn test_config_builder_defaults() -> Result<()> {
410        let config = RunpodConfig::builder().with_api_key("test_key").build()?;
411
412        assert_eq!(config.api_key(), "test_key");
413        assert_eq!(config.rest_url(), "https://rest.runpod.io/v1");
414        assert_eq!(config.timeout(), Duration::from_secs(30));
415
416        Ok(())
417    }
418}
runpod_sdk/client/config.rs

runpod_sdk/client/
config.rs
