feat!: add dynamic authorization support

- add new `AuthProvider` public type to handle an `authorization` token.
- add new `Option<AuthProvider>` as `authorization_provider` in
  `Config`, it holds the dynamic authentication token callback provider.
- add new `Option<AuthProvider>` as `auth_provider` in `RawClient`, it
  holds the dynamic authentication token callback provider.
- add new `authorization` private field in `Request`.
- add new `pub fn with_auth()` to `RawClient` in order to set the
  authorization provider into the client, it should be used following a
  builder patter, the client defaults to no authentication otherwise.
- add new `.with_auth()` method to `Request`, it sets the
  `authorization` token, if any.

- update `pub fn negotiate_protocol_version()` in `RawClient` to return
  the `RawClient`, this way it SHOULD no be used following a builder
  pattern.
- update `.call()` and `.batch_call()` to use the newly added
  `.with_auth()`, instead of updating request's authorization field
  directly.

BREAKING CHANGE: all changes above are API breaking changes.

Author: EddieHouston

Cargo.toml

@@ -48,3 +48,8 @@ openssl = ["dep:openssl"]
 use-rustls = ["rustls"]
 use-rustls-ring = ["rustls-ring"]
 use-openssl = ["openssl"]
+
+# optional dependencies only used in `jwt_dynamic_auth` example
+[dev-dependencies]
+tokio = { version = "1", features = ["full"] }
+bitreq = { version = "0.3.4", features = ["async-https", "json-using-serde"] }

src/client.rs

@@ -112,26 +112,34 @@ impl ClientType {
     /// Constructor that supports multiple backends and allows configuration through
     /// the [Config]
     pub fn from_config(url: &str, config: &Config) -> Result<Self, Error> {
+        let auth_provider = config.authorization_provider().cloned();
+
         #[cfg(any(feature = "openssl", feature = "rustls", feature = "rustls-ring"))]
         if url.starts_with("ssl://") {
             let url = url.replacen("ssl://", "", 1);
             #[cfg(feature = "proxy")]
-            let client = match config.socks5() {
+            let raw_client = match config.socks5() {
                 Some(socks5) => RawClient::new_proxy_ssl(
                     url.as_str(),
                     config.validate_domain(),
                     socks5,
                     config.timeout(),
-                )?,
+                )?
+                .with_auth(auth_provider)
+                .negotiate_protocol_version()?,
                 None => {
                     RawClient::new_ssl(url.as_str(), config.validate_domain(), config.timeout())?
+                        .with_auth(auth_provider)
+                        .negotiate_protocol_version()?
                 }
             };
             #[cfg(not(feature = "proxy"))]
-            let client =
-                RawClient::new_ssl(url.as_str(), config.validate_domain(), config.timeout())?;
+            let raw_client =
+                RawClient::new_ssl(url.as_str(), config.validate_domain(), config.timeout())?
+                    .with_auth(auth_provider)
+                    .negotiate_protocol_version()?;
 
-            return Ok(ClientType::SSL(client));
+            return Ok(ClientType::SSL(raw_client));
         }
 
         #[cfg(not(any(feature = "openssl", feature = "rustls", feature = "rustls-ring")))]
@@ -143,18 +151,27 @@ impl ClientType {
 
         {
             let url = url.replacen("tcp://", "", 1);
+
             #[cfg(feature = "proxy")]
             let client = match config.socks5() {
-                Some(socks5) => ClientType::Socks5(RawClient::new_proxy(
-                    url.as_str(),
-                    socks5,
-                    config.timeout(),
-                )?),
-                None => ClientType::TCP(RawClient::new(url.as_str(), config.timeout())?),
+                Some(socks5) => ClientType::Socks5(
+                    RawClient::new_proxy(url.as_str(), socks5, config.timeout())?
+                        .with_auth(auth_provider)
+                        .negotiate_protocol_version()?,
+                ),
+                None => ClientType::TCP(
+                    RawClient::new(url.as_str(), config.timeout())?
+                        .with_auth(auth_provider)
+                        .negotiate_protocol_version()?,
+                ),
             };
 
             #[cfg(not(feature = "proxy"))]
-            let client = ClientType::TCP(RawClient::new(url.as_str(), config.timeout())?);
+            let client = ClientType::TCP(
+                RawClient::new(url.as_str(), config.timeout())?
+                    .with_auth(auth_provider)
+                    .negotiate_protocol_version()?,
+            );
 
             Ok(client)
         }

src/config.rs

@@ -1,12 +1,16 @@
+use std::sync::Arc;
 use std::time::Duration;
 
+/// A function that provides authorization tokens dynamically (e.g., for JWT refresh)
+pub type AuthProvider = Arc<dyn Fn() -> Option<String> + Send + Sync>;
+
 /// Configuration for an electrum client
 ///
 /// Refer to [`Client::from_config`] and [`ClientType::from_config`].
 ///
 /// [`Client::from_config`]: crate::Client::from_config
 /// [`ClientType::from_config`]: crate::ClientType::from_config
-#[derive(Debug, Clone)]
+#[derive(Clone)]
 pub struct Config {
     /// Proxy socks5 configuration, default None
     socks5: Option<Socks5Config>,
@@ -16,6 +20,24 @@ pub struct Config {
     retry: u8,
     /// when ssl, validate the domain, default true
     validate_domain: bool,
+    /// Optional authorization provider for dynamic token injection
+    authorization_provider: Option<AuthProvider>,
+}
+
+// Custom Debug impl because AuthProvider doesn't implement Debug
+impl std::fmt::Debug for Config {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("Config")
+            .field("socks5", &self.socks5)
+            .field("timeout", &self.timeout)
+            .field("retry", &self.retry)
+            .field("validate_domain", &self.validate_domain)
+            .field(
+                "authorization_provider",
+                &self.authorization_provider.as_ref().map(|_| "<provider>"),
+            )
+            .finish()
+    }
 }
 
 /// Configuration for Socks5
@@ -72,6 +94,12 @@ impl ConfigBuilder {
         self
     }
 
+    /// Sets the authorization provider for dynamic token injection
+    pub fn authorization_provider(mut self, provider: Option<AuthProvider>) -> Self {
+        self.config.authorization_provider = provider;
+        self
+    }
+
     /// Return the config and consume the builder
     pub fn build(self) -> Config {
         self.config
@@ -131,6 +159,13 @@ impl Config {
         self.validate_domain
     }
 
+    /// Get the configuration for `authorization_provider`
+    ///
+    /// Set this with [`ConfigBuilder::authorization_provider`]
+    pub fn authorization_provider(&self) -> Option<&AuthProvider> {
+        self.authorization_provider.as_ref()
+    }
+
     /// Convenience method for calling [`ConfigBuilder::new`]
     pub fn builder() -> ConfigBuilder {
         ConfigBuilder::new()
@@ -144,6 +179,106 @@ impl Default for Config {
             timeout: None,
             retry: 1,
             validate_domain: true,
+            authorization_provider: None,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_authorization_provider_builder() {
+        let token = "test-token-123".to_string();
+        let provider = Arc::new(move || Some(format!("Bearer {}", token)));
+
+        let config = ConfigBuilder::new()
+            .authorization_provider(Some(provider.clone()))
+            .build();
+
+        assert!(config.authorization_provider().is_some());
+
+        // Test that the provider returns the expected value
+        if let Some(auth_provider) = config.authorization_provider() {
+            assert_eq!(auth_provider(), Some("Bearer test-token-123".to_string()));
         }
     }
+
+    #[test]
+    fn test_authorization_provider_none() {
+        let config = ConfigBuilder::new().build();
+
+        assert!(config.authorization_provider().is_none());
+    }
+
+    #[test]
+    fn test_authorization_provider_returns_none() {
+        let provider = Arc::new(|| None);
+
+        let config = ConfigBuilder::new()
+            .authorization_provider(Some(provider))
+            .build();
+
+        assert!(config.authorization_provider().is_some());
+
+        // Test that the provider returns None
+        if let Some(auth_provider) = config.authorization_provider() {
+            assert_eq!(auth_provider(), None);
+        }
+    }
+
+    #[test]
+    fn test_authorization_provider_dynamic_token() {
+        use std::sync::RwLock;
+
+        // Simulate a token that can be updated
+        let token = Arc::new(RwLock::new("initial-token".to_string()));
+        let token_clone = token.clone();
+
+        let provider = Arc::new(move || Some(token_clone.read().unwrap().clone()));
+
+        let config = ConfigBuilder::new()
+            .authorization_provider(Some(provider.clone()))
+            .build();
+
+        // Initial token
+        if let Some(auth_provider) = config.authorization_provider() {
+            assert_eq!(auth_provider(), Some("initial-token".to_string()));
+        }
+
+        // Update the token
+        *token.write().unwrap() = "refreshed-token".to_string();
+
+        // Provider should return the new token
+        if let Some(auth_provider) = config.authorization_provider() {
+            assert_eq!(auth_provider(), Some("refreshed-token".to_string()));
+        }
+    }
+
+    #[test]
+    fn test_config_debug_with_provider() {
+        let provider = Arc::new(|| Some("secret-token".to_string()));
+
+        let config = ConfigBuilder::new()
+            .authorization_provider(Some(provider))
+            .build();
+
+        let debug_str = format!("{:?}", config);
+
+        // Should show <provider> instead of the actual function pointer
+        assert!(debug_str.contains("<provider>"));
+        // Should not leak the token value
+        assert!(!debug_str.contains("secret-token"));
+    }
+
+    #[test]
+    fn test_config_debug_without_provider() {
+        let config = ConfigBuilder::new().build();
+
+        let debug_str = format!("{:?}", config);
+
+        // Should show None for authorization_provider
+        assert!(debug_str.contains("authorization_provider"));
+    }
 }

src/lib.rs

@@ -58,5 +58,5 @@ pub mod utils;
 pub use api::ElectrumApi;
 pub use batch::Batch;
 pub use client::*;
-pub use config::{Config, ConfigBuilder, Socks5Config};
+pub use config::{AuthProvider, Config, ConfigBuilder, Socks5Config};
 pub use types::*;