fix: address PR #16 copilot review — body_raw precedence, 429 retry-after, token-bucket panic guard, TLS init, docs

Author: greysquirr3l

CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.18] - 2026-03-15
+
+### Fixed
+
+- `stygian-graph`: `RestApiAdapter` now checks `body_raw` before `body` when both are present, matching the documented precedence contract
+- `stygian-graph`: `RestApiAdapter` 429 responses now return `ServiceError::RateLimited` with the parsed `Retry-After` value; `send_one` honours the server-specified delay instead of blind exponential backoff
+- `stygian-graph`: token-bucket rate limiter guards against `max_requests = 0` or zero-duration window configs that previously caused a division-by-zero panic via `Duration::from_secs_f64(inf)`
+- `stygian-graph`: `CloudflareCrawlAdapter::with_config` now panics with a clear message on TLS init failure instead of silently falling back to a misconfigured default `reqwest::Client`
+- `book`: Cloudflare crawl adapter metadata example corrected to `job_id`, `pages_crawled`, `output_format` (was `pages`, `url_count`)
+- `book`: `HeadlessMode::Legacy` docs across configuration and env-vars pages corrected to "classic `--headless` for Chromium < 112" (was incorrectly referencing `chrome-headless-shell` and Chrome 132 removal)
+
 ## [0.1.17] - 2026-03-14
 
 ### Added

Cargo.toml

@@ -6,7 +6,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.1.17"
+version = "0.1.18"
 edition = "2024"
 rust-version = "1.93.1"
 authors = ["Nick Campbell <s0ma@protonmail.com>"]

book/src/browser/configuration.md

@@ -50,7 +50,7 @@ let config = BrowserConfig::builder()
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
 | `headless` | `bool` | `true` | Run without visible window |
-| `headless_mode` | `HeadlessMode` | `New` | `New` = `--headless=new` (full Chromium rendering, default since Chrome 112, **only mode since Chrome 132**); `Legacy` = `chrome-headless-shell` / pre-112 `--headless` |
+| `headless_mode` | `HeadlessMode` | `New` | `New` = `--headless=new` (full Chromium rendering, default since Chrome 112); `Legacy` = classic `--headless` flag for Chromium < 112 |
 | `window_size` | `Option<(u32, u32)>` | `(1920, 1080)` | Browser viewport dimensions |
 | `chrome_path` | `Option<PathBuf>` | auto-detect | Path to Chrome/Chromium binary |
 | `stealth_level` | `StealthLevel` | `Advanced` | Anti-detection level |
@@ -92,7 +92,7 @@ All config values can be overridden without touching source code:
 | --- | --- | --- |
 | `STYGIAN_CHROME_PATH` | auto-detect | Path to Chrome/Chromium binary |
 | `STYGIAN_HEADLESS` | `true` | Set `false` for headed mode |
-| `STYGIAN_HEADLESS_MODE` | `new` | `new` (`--headless=new`) or `legacy` (`chrome-headless-shell`; old `--headless` removed in Chrome 132) |
+| `STYGIAN_HEADLESS_MODE` | `new` | `new` (`--headless=new`) or `legacy` (classic `--headless` for Chromium < 112) |
 | `STYGIAN_STEALTH_LEVEL` | `advanced` | `none`, `basic`, `advanced` |
 | `STYGIAN_POOL_MIN` | `2` | Minimum warm browsers |
 | `STYGIAN_POOL_MAX` | `10` | Maximum concurrent browsers |
@@ -161,16 +161,11 @@ let config = BrowserConfig::builder()
 ```
 
 For Chromium ≥ 112 (all modern Chrome / Chromium builds), `New` is the right
-choice. `Legacy` targets are rare: pre-112 Chromium or the separately distributed
-`chrome-headless-shell` binary for lightweight CI workloads where full rendering
-fidelity is not required.
-
-> **Note:** As of Chrome 132 the old `--headless` flag is removed entirely.
-> `HeadlessMode::Legacy` now maps to `chrome-headless-shell` semantics — avoid it
-> unless you are explicitly targeting that binary.
+choice. `Legacy` falls back to the classic `--headless` flag which uses an older
+rendering pipeline — use it only when targeting Chromium < 112.
 
 ```rust,no_run
-// Only needed for Chromium < 112 or chrome-headless-shell
+// Only needed for Chromium < 112
 let config = BrowserConfig::builder()
     .headless_mode(HeadlessMode::Legacy)
     .build();

book/src/graph/adapters.md

@@ -457,9 +457,9 @@ Cloudflare API.
 
 ```json
 {
-  "job_id":    "some-uuid",
-  "pages":     12,
-  "url_count": 12
+  "job_id":        "some-uuid",
+  "pages_crawled": 12,
+  "output_format": "markdown"
 }
 ```
 

book/src/reference/env-vars.md

@@ -11,7 +11,7 @@ variables. No recompilation required.
 | --- | --- | --- |
 | `STYGIAN_CHROME_PATH` | auto-detect | Absolute path to Chrome or Chromium binary |
 | `STYGIAN_HEADLESS` | `true` | `false` for headed mode (displays browser window) |
-| `STYGIAN_HEADLESS_MODE` | `new` | `new` (`--headless=new`) or `legacy` (`chrome-headless-shell`; old `--headless` removed in Chrome 132) |
+| `STYGIAN_HEADLESS_MODE` | `new` | `new` (`--headless=new`) or `legacy` (classic `--headless` for Chromium < 112) |
 | `STYGIAN_STEALTH_LEVEL` | `advanced` | `none`, `basic`, or `advanced` |
 | `STYGIAN_POOL_MIN` | `2` | Minimum warm browser instances |
 | `STYGIAN_POOL_MAX` | `10` | Maximum concurrent browser instances |

crates/stygian-graph/src/adapters/cloudflare_crawl.rs

@@ -161,8 +161,7 @@ impl CloudflareCrawlAdapter {
         let client = Client::builder()
             .timeout(Duration::from_secs(60))
             .build()
-            // reqwest::ClientBuilder::build only fails on TLS init; that is not recoverable.
-            .unwrap_or_default();
+            .expect("reqwest TLS backend failed to initialize");
         Self { client, config }
     }
 

crates/stygian-graph/src/adapters/graphql_rate_limit.rs

@@ -120,6 +120,11 @@ impl RequestWindow {
                 tokens,
                 last_refill,
             } => {
+                // Guard: zero max_requests or zero window would produce rate=0 → inf wait.
+                if self.config.max_requests == 0 || self.config.window.is_zero() {
+                    return Some(max_delay);
+                }
+
                 // Refill tokens proportional to elapsed time.
                 let elapsed = now.duration_since(*last_refill);
                 let rate = f64::from(self.config.max_requests) / self.config.window.as_secs_f64();

crates/stygian-graph/src/adapters/rest_api.rs

@@ -330,12 +330,13 @@ impl RestApiAdapter {
             })
             .unwrap_or_default();
 
-        let body = if params["body"].is_null() {
-            params["body_raw"]
-                .as_str()
-                .map(|raw| RequestBody::Raw(raw.to_owned()))
-        } else {
+        // body_raw takes precedence over body (raw string vs structured JSON).
+        let body = if let Some(raw) = params["body_raw"].as_str().filter(|s| !s.is_empty()) {
+            Some(RequestBody::Raw(raw.to_owned()))
+        } else if !params["body"].is_null() {
             Some(RequestBody::Json(params["body"].clone()))
+        } else {
+            None
         };
 
         let accept = params["accept"]
@@ -438,9 +439,15 @@ impl RestApiAdapter {
 
         for attempt in 0..=self.config.max_retries {
             if attempt > 0 {
-                let delay = self.config.retry_base_delay * 2u32.saturating_pow(attempt - 1);
+                // Honour server Retry-After when available; otherwise exponential backoff.
+                let delay = match &last_err {
+                    Some(StygianError::Service(ServiceError::RateLimited { retry_after_ms })) => {
+                        Duration::from_millis(*retry_after_ms)
+                    }
+                    _ => self.config.retry_base_delay * 2u32.saturating_pow(attempt - 1),
+                };
                 tokio::time::sleep(delay).await;
-                debug!(url, attempt, "REST API retry");
+                debug!(url, attempt, ?delay, "REST API retry");
             }
 
             match self.do_send(url, spec, extra_query).await {
@@ -516,18 +523,18 @@ impl RestApiAdapter {
             .and_then(|v| v.to_str().ok())
             .map(ToOwned::to_owned);
 
-        // 429 — log retry-after hint
+        // 429 — honour server Retry-After hint via dedicated error variant.
         if status.as_u16() == 429 {
-            let retry_after = response
+            let retry_after_secs = response
                 .headers()
                 .get("retry-after")
                 .and_then(|v| v.to_str().ok())
                 .and_then(|s| s.parse::<u64>().ok())
                 .unwrap_or(5);
-            warn!(url, retry_after, "REST API rate-limited (429)");
-            return Err(StygianError::from(ServiceError::Unavailable(format!(
-                "HTTP 429 rate-limited; retry-after={retry_after}s"
-            ))));
+            warn!(url, retry_after_secs, "REST API rate-limited (429)");
+            return Err(StygianError::from(ServiceError::RateLimited {
+                retry_after_ms: retry_after_secs.saturating_mul(1000),
+            }));
         }
 
         if !status.is_success() {
@@ -565,16 +572,19 @@ impl Default for RestApiAdapter {
 
 /// Returns `true` for transient errors that are worth retrying.
 fn is_retryable(err: &StygianError) -> bool {
-    let StygianError::Service(ServiceError::Unavailable(msg)) = err else {
-        return false;
-    };
-    msg.contains("429")
-        || msg.contains("500")
-        || msg.contains("502")
-        || msg.contains("503")
-        || msg.contains("504")
-        || msg.contains("connection")
-        || msg.contains("timed out")
+    match err {
+        StygianError::Service(ServiceError::RateLimited { .. }) => true,
+        StygianError::Service(ServiceError::Unavailable(msg)) => {
+            msg.contains("429")
+                || msg.contains("500")
+                || msg.contains("502")
+                || msg.contains("503")
+                || msg.contains("504")
+                || msg.contains("connection")
+                || msg.contains("timed out")
+        }
+        _ => false,
+    }
 }
 
 // ─── ScrapingService ──────────────────────────────────────────────────────────