fix: improve large subnet scan reliability

asic-rs-core/src/util.rs

@@ -15,6 +15,13 @@ use crate::errors::{ModelSelectionError, RPCError};
 
 /// Default read timeout for RPC stream responses.
 pub const DEFAULT_RPC_TIMEOUT: Duration = Duration::from_secs(5);
+/// Default TCP connection timeout for firmware construction HTTP requests.
+pub const DEFAULT_DISCOVERY_HTTP_CONNECT_TIMEOUT: Duration = Duration::from_secs(2);
+/// Default total timeout for each firmware construction HTTP request.
+///
+/// This includes connection establishment, the request, and response-body
+/// processing.
+pub const DEFAULT_DISCOVERY_HTTP_REQUEST_TIMEOUT: Duration = Duration::from_secs(3);
 
 pub fn unix_timestamp_secs() -> u64 {
     SystemTime::now().duration_since(UNIX_EPOCH).map_or_else(
@@ -27,7 +34,11 @@ pub fn unix_timestamp_secs() -> u64 {
 }
 
 pub fn build_discovery_client() -> Result<reqwest::Client, ModelSelectionError> {
+    // Bound connection establishment separately while enforcing a total
+    // deadline across connection, request, and response-body processing.
     reqwest::Client::builder()
+        .connect_timeout(DEFAULT_DISCOVERY_HTTP_CONNECT_TIMEOUT)
+        .timeout(DEFAULT_DISCOVERY_HTTP_REQUEST_TIMEOUT)
         .pool_max_idle_per_host(0)
         .build()
         .map_err(|_| ModelSelectionError::NoModelResponse)

asic-rs-firmwares/epic/src/firmware.rs

@@ -112,7 +112,6 @@ impl MinerFirmware for EPicFirmware {
             .send()
             .await
             .map_err(|_| ModelSelectionError::NoModelResponse)?;
-
         let json_data = response
             .json::<serde_json::Value>()
             .await

docs/api.md

@@ -8,23 +8,34 @@ differences.
 
 `MinerFactory` owns the scan range and discovery tuning.
 
+Network scans first probe common miner ports concurrently and only then run
+firmware identification. The default limits are 256 addresses for TCP probing
+and 128 addresses for identification, with no TCP retry. `with_concurrent_limit`
+controls identification; connectivity can be tuned independently with the
+`with_connectivity_*` methods. TCP-negative hosts are excluded by default; set
+`with_strict_port_check(false)` to give them a fallback identification pass.
+Firmware construction is capped at five seconds after identification. Its HTTP
+requests use a two-second connection timeout and a three-second total timeout.
+
 === "Rust"
 
     ```rust
     let factory = MinerFactory::from_subnet("192.168.1.0/24")?
-        .with_concurrent_limit(2500)
-        .with_connectivity_timeout_secs(1)
-        .with_identification_timeout_secs(10);
+        .with_concurrent_limit(128)
+        .with_connectivity_timeout_millis(500)
+        .with_identification_timeout_secs(3)
+        .with_miner_construction_timeout_secs(5);
     ```
 
 === "Python"
 
     ```python
     factory = (
         MinerFactory.from_subnet("192.168.1.0/24")
-        .with_concurrent_limit(2500)
-        .with_connectivity_timeout_secs(1)
-        .with_identification_timeout_secs(10)
+        .with_concurrent_limit(128)
+        .with_connectivity_timeout_millis(500)
+        .with_identification_timeout_secs(3)
+        .with_miner_construction_timeout_secs(5)
     )
     ```
 

docs/getting-started.md

@@ -57,6 +57,10 @@ construct the matching miner implementation.
 
 Use a subnet, octet selectors, or range string when the exact IP address is not
 known. Large scans use bounded concurrency.
+TCP reachability and application identification are separate stages. The
+default probe limit is 256 addresses with no retry; responsive addresses are
+then identified with a default concurrency of 128. Probe-negative addresses
+are excluded unless strict port checking is disabled.
 
 === "Rust"
 
@@ -66,7 +70,7 @@ known. Large scans use bounded concurrency.
     #[tokio::main]
     async fn main() -> anyhow::Result<()> {
         let miners = MinerFactory::from_subnet("192.168.1.0/24")?
-            .with_concurrent_limit(2500)
+            .with_concurrent_limit(128)
             .scan()
             .await?;
 
@@ -86,7 +90,7 @@ known. Large scans use bounded concurrency.
     async def main() -> None:
         miners = await (
             MinerFactory.from_subnet("192.168.1.0/24")
-            .with_concurrent_limit(2500)
+            .with_concurrent_limit(128)
             .scan()
         )