lightspeed_sdk/

config.rs

// src/config.rs
use crate::{Priority, LightspeedClient, LightspeedError};
use std::time::Duration;
use url::Url;

/// Configuration settings for the Lightspeed client
/// 
/// Contains all configurable parameters for connecting to and interacting
/// with the Lightspeed service.
#[derive(Debug, Clone)]
pub struct LightspeedConfig {
    /// API key for authentication
    /// 
    /// Obtain your API key from the Solana Vibe Station cloud portal.
    pub api_key: String,
    
    /// SVS RPC URL
    /// 
    /// Your Solana Vibe Station RPC endpoint URL
    /// Example: "https://basic.rpc.solanavibestation.com"
    pub svs_rpc_url: String,
    
    /// Default priority level for transactions
    /// 
    /// Used when sending transactions without explicitly specifying priority.
    pub default_priority: Priority,
    
    /// HTTP request timeout duration
    pub timeout: Duration,
    
    /// Interval between keep-alive requests
    /// 
    /// Only applies when automatic keep-alive is enabled via `start_keep_alive()`.
    pub keep_alive_interval: Duration,
    
    /// Use HTTPS for secure connections
    /// 
    /// Recommended for production environments.
    pub use_https: bool,
    
    /// Enable debug logging
    /// 
    /// When enabled, additional diagnostic information will be logged.
    pub debug: bool,
        
    /// Custom endpoint URL (optional)
    /// 
    /// Primarily used for testing or connecting to alternative endpoints.
    pub custom_endpoint: Option<String>,
}


impl LightspeedConfig {
    /// Process the configuration and return the final endpoint URL
    /// 
    /// If a custom endpoint is set, it uses that directly.
    /// Otherwise, it processes the SVS RPC URL into the Lightspeed format.
    pub fn get_endpoint(&self) -> Result<Url, LightspeedError> {
        if let Some(custom) = &self.custom_endpoint {
            // Use custom endpoint directly for testing
            Url::parse(custom)
                .map_err(|_| LightspeedError::InvalidUrl(custom.clone()))
        } else {
            // Process SVS RPC URL
            if self.svs_rpc_url.is_empty() {
                return Err(LightspeedError::InvalidUrl("SVS RPC URL is required".to_string()));
            }
            Self::process_svs_url(&self.svs_rpc_url)
        }
    }

    /// Process SVS RPC URL into Lightspeed endpoint format
    /// 
    /// Transforms URLs like:
    /// - `https://basic.rpc.solanavibestation.com/?api_key=xxx` 
    /// - `https://ultra.swqos.rpc.solanavibestation.com`
    /// 
    /// Into:
    /// - `https://basic.rpc.solanavibestation.com/lightspeed`
    /// - `https://ultra.swqos.rpc.solanavibestation.com/lightspeed`
    fn process_svs_url(svs_url: &str) -> Result<Url, LightspeedError> {
        // Parse the URL
        let mut url = Url::parse(svs_url)
            .map_err(|_| LightspeedError::InvalidUrl(svs_url.to_string()))?;

        // Remove any query parameters (like ?api_key=)
        url.set_query(None);

        // Ensure it's using a valid scheme
        if url.scheme() != "https" && url.scheme() != "http" {
            return Err(LightspeedError::InvalidUrl(
                format!("URL must use http or https scheme: {}", svs_url)
            ));
        }

        // Validate host
        let host = url.host_str()
            .ok_or_else(|| LightspeedError::InvalidUrl("URL missing host".to_string()))?;

        // Validate it's a solanavibestation.com domain
        if !host.ends_with("solanavibestation.com") {
            return Err(LightspeedError::InvalidUrl(
                format!("URL must be a solanavibestation.com domain: {}", host)
            ));
        }

        // Set the path to /lightspeed
        url.set_path("/lightspeed");

        Ok(url)
    }
}

impl Default for LightspeedConfig {
    fn default() -> Self {
        Self {
            api_key: String::new(),
            svs_rpc_url: String::new(),
            default_priority: Priority::Standard,
            timeout: Duration::from_secs(30),
            keep_alive_interval: Duration::from_secs(20),
            use_https: true,
            debug: false,
            custom_endpoint: None,
        }
    }
}

/// Builder for creating Lightspeed client instances
/// 
/// Provides a fluent interface for configuring the client before initialization.
/// 
/// ## Example
/// 
/// ```rust
/// use lightspeed_sdk::{LightspeedClientBuilder, Priority};
/// use std::time::Duration;
/// 
/// # fn example() -> Result<(), Box<dyn std::error::Error>> {
/// let client = LightspeedClientBuilder::new("your-api-key")
///     .svs_rpc_url("https://basic.rpc.solanavibestation.com") 
///     .default_priority(Priority::Standard)
///     .timeout(Duration::from_secs(60))
///     .debug(true)
///     .build()?;
/// # Ok(())
/// # }
/// ```
pub struct LightspeedClientBuilder {
    config: LightspeedConfig,
}

impl LightspeedClientBuilder {
    /// Creates a new builder with the required API key
    /// 
    /// ## Arguments
    /// 
    /// * `api_key` - Your Lightspeed API key from Solana Vibe Station
    pub fn new(api_key: impl Into<String>) -> Self {
        let mut config = LightspeedConfig::default();
        config.api_key = api_key.into();
        Self { config }
    }

    /// Sets the SVS RPC URL
    /// 
    /// ## Arguments
    /// 
    /// * `url` - Your SVS RPC endpoint URL (e.g., "https://basic.rpc.solanavibestation.com")
    /// 
    /// The URL will be automatically converted to the Lightspeed endpoint format.
    pub fn svs_rpc_url(mut self, url: impl Into<String>) -> Self {
        self.config.svs_rpc_url = url.into();
        self
    }

    /// Sets the default priority for transactions
    /// 
    /// Transactions sent without specifying priority will use this setting.
    /// 
    /// ## Arguments
    /// 
    /// * `priority` - Default priority level
    pub fn default_priority(mut self, priority: Priority) -> Self {
        self.config.default_priority = priority;
        self
    }

    /// Sets the HTTP request timeout
    /// 
    /// ## Arguments
    /// 
    /// * `timeout` - Maximum duration for HTTP requests
    pub fn timeout(mut self, timeout: Duration) -> Self {
        self.config.timeout = timeout;
        self
    }

    /// Sets the keep-alive interval
    /// 
    /// Determines how frequently keep-alive requests are sent when
    /// automatic keep-alive is enabled.
    /// 
    /// ## Arguments
    /// 
    /// * `interval` - Duration between keep-alive requests
    pub fn keep_alive_interval(mut self, interval: Duration) -> Self {
        self.config.keep_alive_interval = interval;
        self
    }

    /// Enables or disables HTTPS
    /// 
    /// ## Arguments
    /// 
    /// * `enabled` - Whether to use HTTPS (recommended for production)
    pub fn use_https(mut self, enabled: bool) -> Self {
        self.config.use_https = enabled;
        self
    }

    /// Enables or disables debug logging
    /// 
    /// ## Arguments
    /// 
    /// * `enabled` - Whether to enable debug output
    pub fn debug(mut self, enabled: bool) -> Self {
        self.config.debug = enabled;
        self
    }

    /// Sets a custom endpoint URL
    /// 
    /// This is primarily intended for testing or connecting to
    /// alternative Lightspeed deployments. When set, this overrides
    /// the SVS RPC URL processing.
    /// 
    /// ## Arguments
    /// 
    /// * `endpoint` - Custom endpoint URL
    pub fn custom_endpoint(mut self, endpoint: impl Into<String>) -> Self {
        self.config.custom_endpoint = Some(endpoint.into());
        self
    }

    /// Builds and returns the configured Lightspeed client
    /// 
    /// ## Errors
    /// 
    /// Returns an error if client initialization fails due to invalid
    /// configuration or network issues.
    pub fn build(self) -> Result<LightspeedClient, LightspeedError> {
        LightspeedClient::new(self.config)
    }
}