feat: 添加 DNS 预解析功能及超时配置

新增支持禁用 DNS 预解析和自定义 DNS 解析超时时间，扩展同步和异步 ping 相关接口及流式接口，完善示例代码。

Author: a76yyyy

python/examples/basic_usage.py

@@ -45,6 +45,16 @@ def sync_examples():
     result = pinger.ping_once()
     print(f"IPv4-only ping: {result}")
 
+    # 禁用 DNS 预解析
+    pinger = Pinger("8.8.8.8", dns_pre_resolve=False)
+    result = pinger.ping_once()
+    print(f"Ping without DNS pre-resolve: {result}")
+
+    # 自定义 DNS 解析超时
+    pinger = Pinger("8.8.8.8", dns_resolve_timeout_ms=5000)
+    result = pinger.ping_once()
+    print(f"Ping with custom DNS timeout: {result}")
+
 
 async def async_examples():
     """异步 API 示例"""

python/ping_rs/_ping_rs.pyi

@@ -120,6 +120,8 @@ class Pinger:
         interface: str | None = None,
         ipv4: bool = False,
         ipv6: bool = False,
+        dns_pre_resolve: bool = True,
+        dns_resolve_timeout_ms: int | None = None,
     ) -> Pinger: ...
     def ping_once(self) -> PingResult:
         """Execute a single ping synchronously."""
@@ -143,6 +145,8 @@ class AsyncPinger:
         interface: str | None = None,
         ipv4: bool = False,
         ipv6: bool = False,
+        dns_pre_resolve: bool = True,
+        dns_resolve_timeout_ms: int | None = None,
     ) -> AsyncPinger: ...
     async def ping_once(self) -> PingResult:
         """Execute a single ping asynchronously."""
@@ -167,6 +171,8 @@ class PingStream:
         ipv4: bool = False,
         ipv6: bool = False,
         max_count: int | None = None,
+        dns_pre_resolve: bool = True,
+        dns_resolve_timeout_ms: int | None = None,
     ) -> PingStream: ...
     def try_recv(self) -> PingResult | None:
         """Try to receive the next ping result without blocking."""
@@ -204,6 +210,8 @@ class AsyncPingStream:
         ipv4: bool = False,
         ipv6: bool = False,
         max_count: int | None = None,
+        dns_pre_resolve: bool = True,
+        dns_resolve_timeout_ms: int | None = None,
     ) -> AsyncPingStream: ...
     def __aiter__(self) -> AsyncPingStream:
         """Return self as an async iterator."""
@@ -223,6 +231,8 @@ def ping_once(
     interface: str | None = None,
     ipv4: bool = False,
     ipv6: bool = False,
+    dns_pre_resolve: bool = True,
+    dns_resolve_timeout_ms: int | None = None,
 ) -> PingResult:
     """Execute a single ping operation synchronously."""
     ...
@@ -233,6 +243,8 @@ async def ping_once_async(
     interface: str | None = None,
     ipv4: bool = False,
     ipv6: bool = False,
+    dns_pre_resolve: bool = True,
+    dns_resolve_timeout_ms: int | None = None,
 ) -> PingResult:
     """Execute a single ping operation asynchronously."""
     ...
@@ -245,6 +257,8 @@ def ping_multiple(
     interface: str | None = None,
     ipv4: bool = False,
     ipv6: bool = False,
+    dns_pre_resolve: bool = True,
+    dns_resolve_timeout_ms: int | None = None,
 ) -> list[PingResult]:
     """Execute multiple ping operations synchronously."""
     ...
@@ -257,6 +271,8 @@ async def ping_multiple_async(
     interface: str | None = None,
     ipv4: bool = False,
     ipv6: bool = False,
+    dns_pre_resolve: bool = True,
+    dns_resolve_timeout_ms: int | None = None,
 ) -> list[PingResult]:
     """Execute multiple ping operations asynchronously."""
     ...
@@ -268,6 +284,8 @@ def create_ping_stream(
     ipv4: bool = False,
     ipv6: bool = False,
     count: int | None = None,
+    dns_pre_resolve: bool = True,
+    dns_resolve_timeout_ms: int | None = None,
 ) -> PingStream:
     """Create a non-blocking ping stream."""
     ...

src/lib.rs

@@ -5,6 +5,8 @@
 //! This library provides both synchronous and asynchronous ping implementations,
 //! as well as streaming interfaces for continuous ping operations.
 
+#![allow(clippy::too_many_arguments)] // 添加允许多参数的属性
+
 mod protocols;
 mod types;
 mod utils;
@@ -24,17 +26,28 @@ pub use types::result::PingResult;
 
 /// 创建非阻塞 ping 流
 #[pyfunction]
-#[pyo3(signature = (target, interval_ms=1000, interface=None, ipv4=false, ipv6=false, count=None))]
+#[pyo3(signature = (target, interval_ms=1000, interface=None, ipv4=false, ipv6=false, count=None, dns_pre_resolve=true, dns_resolve_timeout_ms=None))]
 fn create_ping_stream(
     target: &Bound<PyAny>,
     interval_ms: i64,
     interface: Option<String>,
     ipv4: bool,
     ipv6: bool,
     count: Option<usize>,
+    dns_pre_resolve: bool,
+    dns_resolve_timeout_ms: Option<i64>,
 ) -> PyResult<PingStream> {
     // 直接使用 PingStream 的构造函数
-    PingStream::new(target, interval_ms, interface, ipv4, ipv6, count)
+    PingStream::new(
+        target,
+        interval_ms,
+        interface,
+        ipv4,
+        ipv6,
+        count,
+        dns_pre_resolve,
+        dns_resolve_timeout_ms,
+    )
 }
 
 /// 执行单次 ping（同步版本）
@@ -43,17 +56,27 @@ fn create_ping_stream(
 /// - `timeout_ms`: 等待响应的超时时间（毫秒），默认 1000ms
 ///   注意：内部实现中，这个值会被用作 `interval_ms` 传递给底层 ping 命令
 #[pyfunction]
-#[pyo3(signature = (target, timeout_ms=1000, interface=None, ipv4=false, ipv6=false))]
+#[pyo3(signature = (target, timeout_ms=1000, interface=None, ipv4=false, ipv6=false, dns_pre_resolve=true, dns_resolve_timeout_ms=None))]
 fn ping_once(
     target: &Bound<PyAny>,
     timeout_ms: i64,
     interface: Option<String>,
     ipv4: bool,
     ipv6: bool,
+    dns_pre_resolve: bool,
+    dns_resolve_timeout_ms: Option<i64>,
 ) -> PyResult<PingResult> {
     // 创建 Pinger 实例
     // 注意：这里将 timeout_ms 作为 interval_ms 传递，因为 ping_once 中会将其用作超时时间
-    let pinger = Pinger::new(target, timeout_ms, interface, ipv4, ipv6)?;
+    let pinger = Pinger::new(
+        target,
+        timeout_ms,
+        interface,
+        ipv4,
+        ipv6,
+        dns_pre_resolve,
+        dns_resolve_timeout_ms,
+    )?;
 
     // 执行 ping_once
     pinger.ping_once()
@@ -65,26 +88,36 @@ fn ping_once(
 /// - `timeout_ms`: 等待响应的超时时间（毫秒），默认 1000ms
 ///   注意：内部实现中，这个值会被用作 `interval_ms` 传递给底层 ping 命令
 #[pyfunction]
-#[pyo3(signature = (target, timeout_ms=1000, interface=None, ipv4=false, ipv6=false))]
+#[pyo3(signature = (target, timeout_ms=1000, interface=None, ipv4=false, ipv6=false, dns_pre_resolve=true, dns_resolve_timeout_ms=None))]
 fn ping_once_async<'py>(
     py: Python<'py>,
     target: &Bound<PyAny>,
     timeout_ms: i64,
     interface: Option<String>,
     ipv4: bool,
     ipv6: bool,
+    dns_pre_resolve: bool,
+    dns_resolve_timeout_ms: Option<i64>,
 ) -> PyResult<Bound<'py, PyAny>> {
     // 创建 AsyncPinger 实例
     // 注意：这里将 timeout_ms 作为 interval_ms 传递，因为 ping_once 中会将其用作超时时间
-    let pinger = AsyncPinger::new(target, timeout_ms, interface, ipv4, ipv6)?;
+    let pinger = AsyncPinger::new(
+        target,
+        timeout_ms,
+        interface,
+        ipv4,
+        ipv6,
+        dns_pre_resolve,
+        dns_resolve_timeout_ms,
+    )?;
 
     // 执行异步 ping_once
     pinger.ping_once(py)
 }
 
 /// 执行多次 ping（同步版本）
 #[pyfunction]
-#[pyo3(signature = (target, count=4, interval_ms=1000, timeout_ms=None, interface=None, ipv4=false, ipv6=false))]
+#[pyo3(signature = (target, count=4, interval_ms=1000, timeout_ms=None, interface=None, ipv4=false, ipv6=false, dns_pre_resolve=true, dns_resolve_timeout_ms=None))]
 fn ping_multiple(
     target: &Bound<PyAny>,
     count: i32,
@@ -93,17 +126,27 @@ fn ping_multiple(
     interface: Option<String>,
     ipv4: bool,
     ipv6: bool,
+    dns_pre_resolve: bool,
+    dns_resolve_timeout_ms: Option<i64>,
 ) -> PyResult<Vec<PingResult>> {
     // 创建 Pinger 实例
-    let pinger = Pinger::new(target, interval_ms, interface, ipv4, ipv6)?;
+    let pinger = Pinger::new(
+        target,
+        interval_ms,
+        interface,
+        ipv4,
+        ipv6,
+        dns_pre_resolve,
+        dns_resolve_timeout_ms,
+    )?;
 
     // 执行 ping_multiple
     pinger.ping_multiple(count, timeout_ms)
 }
 
 /// 执行多次 ping（异步版本）
 #[pyfunction]
-#[pyo3(signature = (target, count=4, interval_ms=1000, timeout_ms=None, interface=None, ipv4=false, ipv6=false))]
+#[pyo3(signature = (target, count=4, interval_ms=1000, timeout_ms=None, interface=None, ipv4=false, ipv6=false, dns_pre_resolve=true, dns_resolve_timeout_ms=None))]
 #[allow(clippy::too_many_arguments)] // 添加允许多参数的属性
 fn ping_multiple_async<'py>(
     py: Python<'py>,
@@ -114,9 +157,19 @@ fn ping_multiple_async<'py>(
     interface: Option<String>,
     ipv4: bool,
     ipv6: bool,
+    dns_pre_resolve: bool,
+    dns_resolve_timeout_ms: Option<i64>,
 ) -> PyResult<Bound<'py, PyAny>> {
     // 创建 AsyncPinger 实例
-    let pinger = AsyncPinger::new(target, interval_ms, interface, ipv4, ipv6)?;
+    let pinger = AsyncPinger::new(
+        target,
+        interval_ms,
+        interface,
+        ipv4,
+        ipv6,
+        dns_pre_resolve,
+        dns_resolve_timeout_ms,
+    )?;
 
     // 执行异步 ping_multiple
     pinger.ping_multiple(py, count, timeout_ms)

src/protocols/icmp/ping/async_ping.rs

@@ -17,6 +17,7 @@ pub struct AsyncPinger {
     interface: Option<String>,
     ipv4: bool,
     ipv6: bool,
+    dns_options: platform::DnsPreResolveOptions,
 }
 
 #[pymethods]
@@ -29,30 +30,46 @@ impl AsyncPinger {
     /// - `interface`: Network interface to use (optional)
     /// - `ipv4`: Force IPv4 (default: false)
     /// - `ipv6`: Force IPv6 (default: false)
+    /// - `dns_pre_resolve`: Enable DNS pre-resolution (default: true)
+    /// - `dns_resolve_timeout_ms`: DNS resolution timeout in milliseconds (default: None, uses `interval_ms`)
     ///
     /// # Errors
     /// - `PyValueError`: If `interval_ms` is negative, less than 100ms, or not a multiple of 100ms
     /// - `PyTypeError`: If the target cannot be converted to a string
     #[new]
-    #[pyo3(signature = (target, interval_ms=1000, interface=None, ipv4=false, ipv6=false))]
+    #[pyo3(signature = (target, interval_ms=1000, interface=None, ipv4=false, ipv6=false, dns_pre_resolve=true, dns_resolve_timeout_ms=None))]
     pub fn new(
         target: &Bound<PyAny>,
         interval_ms: i64,
         interface: Option<String>,
         ipv4: bool,
         ipv6: bool,
+        dns_pre_resolve: bool,
+        dns_resolve_timeout_ms: Option<i64>,
     ) -> PyResult<Self> {
         let target_str = extract_target(target)?;
 
         // 验证 interval_ms 参数
         let interval_ms_u64 = validate_interval_ms(interval_ms, "interval_ms")?;
 
+        // 处理 DNS 超时参数
+        let dns_timeout = if let Some(timeout_ms) = dns_resolve_timeout_ms {
+            let timeout_u64 = crate::utils::validation::i64_to_u64_positive(timeout_ms, "dns_resolve_timeout_ms")?;
+            Some(std::time::Duration::from_millis(timeout_u64))
+        } else {
+            None
+        };
+
         Ok(Self {
             target: target_str,
             interval_ms: interval_ms_u64,
             interface,
             ipv4,
             ipv6,
+            dns_options: platform::DnsPreResolveOptions {
+                enable: dns_pre_resolve,
+                timeout: dns_timeout,
+            },
         })
     }
 
@@ -66,14 +83,15 @@ impl AsyncPinger {
         let interface = self.interface.clone();
         let ipv4 = self.ipv4;
         let ipv6 = self.ipv6;
+        let dns_options = self.dns_options;
 
         future_into_py(py, async move {
             let options = create_ping_options(&target, interval_ms, interface, ipv4, ipv6);
 
             let interval_duration = std::time::Duration::from_millis(interval_ms);
 
             // 获取异步通道
-            let mut receiver = platform::execute_ping_async(options)
+            let mut receiver = platform::execute_ping_async(options, dns_options)
                 .await
                 .map_err(|e| PyErr::new::<PyRuntimeError, _>(format!("Failed to start ping: {e}")))?;
 
@@ -120,14 +138,15 @@ impl AsyncPinger {
         let interface = self.interface.clone();
         let ipv4 = self.ipv4;
         let ipv6 = self.ipv6;
+        let dns_options = self.dns_options;
 
         future_into_py(py, async move {
             // 不传递 count 给底层 ping 命令，由 Rust 层控制接收数量
             let options = create_ping_options(&target, interval_ms, interface, ipv4, ipv6);
             let start_time = Instant::now();
 
             // 获取异步通道
-            let mut receiver = platform::execute_ping_async(options)
+            let mut receiver = platform::execute_ping_async(options, dns_options)
                 .await
                 .map_err(|e| PyErr::new::<PyRuntimeError, _>(format!("Failed to start ping: {e}")))?;