feat: client connect over tcp and tls

Cargo.toml

@@ -4,23 +4,30 @@ version = "0.4.0"
 description = "Experimental but sane electrum client by @evanlinjin."
 license = "MIT OR Apache-2.0"
 edition = "2021"
-rust-version = "1.70"
+rust-version = "1.71"
 repository = "https://github.com/bitcoindevkit/electrum_streaming_client"
 documentation = "https://docs.rs/electrum_streaming_client"
 readme = "README.md"
 
+[package.metadata.docs.rs]
+all-features = true
+
 [dependencies]
 futures = "0.3"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 bitcoin = { version = "0.32", features = ["serde"] }
 
-tokio = { version = "1.44.2", features = ["io-util"],  optional = true }
+tokio = { version = "1.44.2", features = ["io-util", "net", "time"], optional = true }
 tokio-util = { version = "0.7.15", features = ["compat"], optional = true }
+tokio-rustls = { version = "0.26", optional = true }
+rustls = { version = "0.23", optional = true }
+webpki-roots = { version = "1", optional = true }
 
 [features]
 default = ["tokio"]
 tokio = ["dep:tokio", "tokio-util"]
+ssl = ["dep:rustls", "dep:webpki-roots", "dep:tokio-rustls"]
 
 [dev-dependencies]
 async-std = "1.13.0"

README.md

@@ -16,15 +16,16 @@ models.
 ## Example (async with Tokio)
 
 ```rust,no_run
-use electrum_streaming_client::{AsyncClient, Event};
-use tokio::net::TcpStream;
+use std::time::Duration;
+
+use electrum_streaming_client::{AsyncClient, ServerAddr};
 use futures::StreamExt;
 
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
-    let stream = TcpStream::connect("127.0.0.1:50001").await?;
-    let (reader, writer) = stream.into_split();
-    let (client, mut events, worker) = AsyncClient::new_tokio(reader, writer);
+    let addr: ServerAddr = "127.0.0.1:50001".parse()?;
+    let (client, mut events, worker) =
+        AsyncClient::connect_tcp(&addr, Some(Duration::from_secs(10))).await?;
 
     tokio::spawn(worker); // spawn the client worker task
 
@@ -41,9 +42,9 @@ async fn main() -> anyhow::Result<()> {
 
 ## Optional Features
 
-- `tokio`: Enables [`AsyncClient::new_tokio`] for use with Tokio-compatible streams.
+- `tokio`: Enables [`AsyncClient::new_tokio`] and [`AsyncClient::connect_tcp`].
+- `ssl`: Enables TLS via rustls (`BlockingClient::connect_ssl`; `AsyncClient::connect_ssl`).
 
 ## License
 
 MIT
-

src/client.rs

@@ -179,6 +179,43 @@ impl AsyncClient {
         self.tx.close_channel();
     }
 
+    /// Creates a new [`AsyncClient`] connected to `addr` over plaintext TCP via Tokio.
+    #[cfg(feature = "tokio")]
+    pub async fn connect_tcp(
+        addr: &crate::transport::ServerAddr,
+        timeout: Option<std::time::Duration>,
+    ) -> std::io::Result<(
+        Self,
+        AsyncEventReceiver,
+        impl std::future::Future<Output = std::io::Result<()>> + Send,
+    )> {
+        let stream = crate::transport::tokio::connect_tcp(addr, timeout).await?;
+        let (reader, writer) = tokio::io::split(stream);
+        Ok(Self::new_tokio(reader, writer))
+    }
+
+    /// Creates a new [`AsyncClient`] connected to `addr` over TLS via Tokio.
+    ///
+    /// `timeout` bounds DNS, TCP connect, and the TLS handshake.
+    /// `validate_domain` requires a domain host.
+    #[cfg(all(feature = "ssl", feature = "tokio"))]
+    pub async fn connect_ssl(
+        addr: &crate::transport::ServerAddr,
+        validate_domain: bool,
+        timeout: Option<std::time::Duration>,
+    ) -> Result<
+        (
+            Self,
+            AsyncEventReceiver,
+            impl std::future::Future<Output = std::io::Result<()>> + Send,
+        ),
+        crate::TlsConnectError,
+    > {
+        let stream = crate::transport::tokio::connect_ssl(addr, validate_domain, timeout).await?;
+        let (reader, writer) = tokio::io::split(stream);
+        Ok(Self::new_tokio(reader, writer))
+    }
+
     /// Sends a single tracked request to the Electrum server and awaits the response.
     ///
     /// This method is for request–response style interactions where only a single result is
@@ -344,6 +381,46 @@ impl BlockingClient {
         (Self { tx: req_tx }, event_recv, read_join, write_join)
     }
 
+    /// Creates a new [`BlockingClient`] connected to `addr` over plaintext TCP.
+    #[allow(clippy::type_complexity)]
+    pub fn connect_tcp(
+        addr: &crate::transport::ServerAddr,
+        timeout: Option<std::time::Duration>,
+    ) -> std::io::Result<(
+        Self,
+        BlockingEventReceiver,
+        std::thread::JoinHandle<std::io::Result<()>>,
+        std::thread::JoinHandle<std::io::Result<()>>,
+    )> {
+        let writer = crate::transport::blocking::connect_tcp(addr, timeout)?;
+        let reader = writer.try_clone()?;
+        Ok(Self::new(reader, writer))
+    }
+
+    /// Creates a new [`BlockingClient`] connected to `addr` over TLS.
+    ///
+    /// `timeout` bounds TCP connect and the TLS handshake.
+    /// `validate_domain` requires a domain host.
+    #[cfg(feature = "ssl")]
+    #[allow(clippy::type_complexity)]
+    pub fn connect_ssl(
+        addr: &crate::transport::ServerAddr,
+        validate_domain: bool,
+        timeout: Option<std::time::Duration>,
+    ) -> Result<
+        (
+            Self,
+            BlockingEventReceiver,
+            std::thread::JoinHandle<std::io::Result<()>>,
+            std::thread::JoinHandle<std::io::Result<()>>,
+        ),
+        crate::TlsConnectError,
+    > {
+        let stream = crate::transport::blocking::connect_ssl(addr, validate_domain, timeout)?;
+        let (reader, writer) = stream.into_split();
+        Ok(Self::new(reader, writer))
+    }
+
     /// Sends a single tracked request to the Electrum server and waits for its response.
     ///
     /// This method blocks the current thread until the server replies. It is intended for