staged stream execution path

Author: zekageri

CHANGELOG.md

@@ -8,6 +8,9 @@ All notable changes to this project will be documented in this file.
 - Streaming download API via `getStream()` for binary or arbitrary content (no JSON handling).
 - Chunk-based delivery using `FetchChunkCallback` to process large payloads incrementally (files, firmware, blobs).
 - Completion callback with `StreamResult` containing transport error, HTTP status code, and total received byte count.
+- Status-gated streaming overloads with `FetchStreamStartCallback` and
+  `StreamStartInfo` so callers can reject non-`2xx` responses before any body
+  chunk is processed.
 - Per-request streaming size limits via `FetchRequestOptions::maxBodyBytes` (default: unlimited for streams).
 - Added global (`FetchConfig`) and per-request (`FetchRequestOptions`) TX/RX HTTP client buffer sizing controls.
 - Added explicit HTTPS trust-source configuration to `FetchConfig` and per-request TLS overrides to `FetchRequestOptions` (`caCertPem`, `useTlsCertBundle`, `useGlobalCaStore`, `skipTlsServerCertValidation`, `skipTlsCommonNameCheck`).
@@ -18,6 +21,9 @@ All notable changes to this project will be documented in this file.
 - Added `isInitialized()` as the public runtime-state contract accessor.
 
 ### Fixed
+- Stream requests can now resolve HTTP status, content length, and chunked mode
+  before chunk delivery when callers use the new status-aware overload, which
+  prevents OTA/file consumers from processing HTML or error bodies as payload.
 - Normalize malformed `http:/` or `https:/` URLs to `http://`/`https://` to avoid DNS failures with parsed hosts like `:example.com`.
 - Collapse extra slashes (`https:///`) and strip a leading `://:` host typo before handing URLs to esp_http_client.
 - HTTPS requests now default to ESP certificate-bundle verification, matching the expected mixed Arduino + ESP-IDF transport behavior for public endpoints.

README.md

@@ -201,6 +201,44 @@ if (!started) {
 }
 ```
 
+### Status-Gated Streaming Example
+
+Use the status-aware overload when you must reject non-`2xx` responses before
+processing any body bytes, for example during OTA or direct-to-flash writes.
+
+```cpp
+const char* exampleURL = "https://example.com/firmware.bin";
+
+bool handleStart(const StreamStartInfo& info){
+    if (info.statusCode < 200 || info.statusCode >= 300) {
+        ESP_LOGW("FETCH", "Rejecting response with HTTP %d", info.statusCode);
+        return false;
+    }
+    return true;
+}
+
+bool handleChunk(const void* data, size_t size){
+    return true;
+}
+
+void handleDone(StreamResult result){
+    ESP_LOGI("FETCH", "Finished: status=%d error=%s bytes=%u",
+        result.statusCode,
+        esp_err_to_name(result.error),
+        result.receivedBytes
+    );
+}
+
+fetch.getStream(exampleURL, handleStart, handleChunk, handleDone);
+```
+
+If `handleStart(...)` returns `false`:
+
+* no chunk callback is invoked
+* `StreamResult.error == ESP_OK`
+* `StreamResult.statusCode` contains the resolved HTTP status
+* `StreamResult.receivedBytes == 0`
+
 ---
 
 ### Streaming Size Limits
@@ -370,11 +408,33 @@ bool getStream(const String& url,
     FetchStreamCallback onDone = nullptr,
     const FetchRequestOptions& opts = {}
 );
+
+bool getStream(const char* url,
+    FetchStreamStartCallback onStart,
+    FetchChunkCallback onChunk,
+    FetchStreamCallback onDone = nullptr,
+    const FetchRequestOptions& opts = {}
+);
+
+bool getStream(const String& url,
+    FetchStreamStartCallback onStart,
+    FetchChunkCallback onChunk,
+    FetchStreamCallback onDone = nullptr,
+    const FetchRequestOptions& opts = {}
+);
 ```
 
 #### Callbacks
 
 ```cpp
+struct StreamStartInfo {
+    int statusCode;
+    int64_t contentLength;
+    bool isChunked;
+};
+
+using FetchStreamStartCallback = std::function<bool(const StreamStartInfo& info)>;
+
 using FetchChunkCallback = std::function<bool(const void* data, size_t size)>;
 
 using FetchStreamCallback = std::function<void(StreamResult result)>;
@@ -386,6 +446,10 @@ struct StreamResult {
 };
 ```
 
+Use `FetchStreamStartCallback` when the caller needs to validate HTTP status
+before processing any response body bytes. Legacy `getStream(...)` overloads
+without `onStart` remain available for existing callers.
+
 ---
 
 ## Result Shape (JSON Mode)