@alteriom/painlessmesh 2.0.3 → 2.1.0

package/examples/sendToInternet/sendToInternet.ino

@@ -49,10 +49,24 @@
 // For Callmebot WhatsApp API:
 // - Get your API key from https://www.callmebot.com/blog/free-api-whatsapp-messages/
 // - Format: https://api.callmebot.com/whatsapp.php?phone=PHONE&apikey=KEY&text=MESSAGE
+// - CallMeBot is a free service with a rate limit, and it does not say in
+//   the HTTP status whether it will deliver: callmebot.h reads its reply.
+//   Send it alerts, not a message every minute.
+//
+// What painlessMesh does and does not do for you:
+// - It issues each request once. It retries only when the request cannot
+//   have reached the server (the connection was refused, say) or the server
+//   said to come back (HTTP 429/503, honouring Retry-After). A timeout after
+//   the request was sent is NOT retried: resending could deliver it twice.
+// - Every attempt carries the same X-Request-Id / Idempotency-Key header.
+// - The callback gets the HTTP status and the start of the response body.
+//   Whether that reply means "delivered" is the service's language, so the
+//   sketch decides -- here with callmebot::judge().
 //
 //************************************************************
 #include "painlessMesh.h"
-#include <WiFiClientSecure.h>
+
+#include "callmebot.h"
 
 // ============================================
 // Mesh Network Configuration
@@ -95,9 +109,18 @@
 #define TEMP_RANGE      10.0   // Temperature range (20-30°C)
 #define HUMIDITY_MIN    40.0   // Minimum humidity (%)
 #define HUMIDITY_RANGE  40.0   // Humidity range (40-80%)
-#define O2_MIN          5.0    // Minimum O2 level (mg/L)
-#define O2_RANGE        5.0    // O2 range (5-10 mg/L)
-#define O2_ALARM_THRESHOLD 6.0 // O2 level below this triggers alarm
+#define O2_MIN          5.0    // Lowest simulated O2 level (mg/L)
+#define O2_MAX          10.0   // Highest simulated O2 level (mg/L)
+#define O2_ALARM_THRESHOLD 6.0 // O2 level below this raises the alarm
+#define O2_ALARM_CLEAR     6.5 // ...and it clears only above this (hysteresis)
+
+// ============================================
+// Alert pacing
+// ============================================
+// One WhatsApp per alarm, not one per reading, and never more often than
+// this per node. A reading every minute that alerted every time it was low
+// is how a sketch runs into CallMeBot's rate limit.
+#define ALERT_MIN_INTERVAL_MS (10UL * 60UL * 1000UL)
 
 // ============================================
 // Mode Selection
@@ -115,7 +138,7 @@ painlessMesh mesh;
 // ============================================
 // Function Prototypes
 // ============================================
-void sendAlertToWhatsApp(String message);
+bool sendAlertToWhatsApp(String message, bool isO2Alarm = false);
 void sendSensorDataToCloud();
 void receivedCallback(uint32_t from, String& msg);
 void newConnectionCallback(uint32_t nodeId);
@@ -137,6 +160,13 @@ void sendStartupAlert();
 Task taskStartupAlert(30000, TASK_FOREVER, &sendStartupAlert);
 String startupMsg;
 
+// Alert state
+bool alertInFlight = false;          // a WhatsApp request is on its way
+uint32_t lastAlertMs = 0;            // when the last one was handed over
+uint32_t alertHoldMs = 0;            // how long to wait after it
+bool o2Alarm = false;                // the alarm is raised
+float o2Level = 8.0;                 // simulated reading, a slow random walk
+
 // ============================================
 // URL Encoding Helper
 // ============================================
@@ -175,61 +205,97 @@ String urlEncode(const String& str) {
 
 /**
  * Send a WhatsApp message via Callmebot using sendToInternet()
- * 
+ *
  * This function demonstrates how to use mesh.sendToInternet() to send
  * data to an Internet endpoint. The request is automatically routed
  * through a gateway node that has Internet access.
- * 
+ *
  * @param message The message to send via WhatsApp
+ * @param isO2Alarm true for the O2 alarm, which is re-armed if CallMeBot
+ *                  does not take the message
+ * @return true when the request was handed to the mesh
  */
-void sendAlertToWhatsApp(String message) {
+bool sendAlertToWhatsApp(String message, bool isO2Alarm) {
   // Check if Internet is available via any gateway
   if (!mesh.hasInternetConnection()) {
     Serial.println("❌ No Internet available - no gateway with Internet found");
     Serial.println("   Make sure at least one node is a bridge with router access");
-    return;
+    return false;
   }
-  
+  if (alertInFlight) {
+    Serial.println("(a WhatsApp message is still on its way; not sending another)");
+    return false;
+  }
+  if (lastAlertMs != 0 && millis() - lastAlertMs < alertHoldMs) {
+    Serial.printf("(WhatsApp paused for another %lu s after the last message)\n",
+                  (unsigned long)((alertHoldMs - (millis() - lastAlertMs)) / 1000));
+    return false;
+  }
+
   // URL-encode the message for safe transmission
   String encodedMessage = urlEncode(message);
-  
+
   // Build the Callmebot WhatsApp API URL
   // Format: https://api.callmebot.com/whatsapp.php?phone=PHONE&apikey=KEY&text=MESSAGE
   String url = "https://api.callmebot.com/whatsapp.php";
-  url += "?phone=" + String(WHATSAPP_PHONE);
+  url += "?phone=" + urlEncode(WHATSAPP_PHONE);
   url += "&apikey=" + String(WHATSAPP_APIKEY);
   url += "&text=" + encodedMessage;
-  
+
   Serial.println("\n📱 Sending WhatsApp message via sendToInternet()...");
   Serial.printf("   Message: %s\n", message.c_str());
-  Serial.printf("   URL: %s\n", url.c_str());
-  
-  // Use sendToInternet() to route the request through a gateway
-  // The callback will be invoked when we get a response (or timeout)
+  // Logs end up pasted into bug reports; the key stays out of them.
+  Serial.printf("   URL: %s\n", callmebot::redactApiKey(url).c_str());
+
+  // Use sendToInternet() to route the request through a gateway.
   //
-  // The gateway reads the response body, not only the status: CallMeBot
-  // answers a refusal ("Too many requests") with HTTP 201 or 203, so a 2xx
-  // alone proves nothing. A refusal arrives here as success=false with the
-  // service's own words in `error`; HTTP 203 stays a failure because a proxy,
-  // not WhatsApp, may have answered.
+  // This callback receives the whole InternetResult: the HTTP status, the
+  // start of CallMeBot's reply, whether the library could retry it and how
+  // many requests it took. painlessMesh says what HTTP says; callmebot::judge()
+  // says what CallMeBot meant -- a "Too many requests" page can arrive under
+  // HTTP 201, and HTTP 208 has meant "not delivered".
+  alertInFlight = true;
+  lastAlertMs = millis();
+  alertHoldMs = ALERT_MIN_INTERVAL_MS;
   uint32_t msgId = mesh.sendToInternet(
     url,
     "",  // No payload needed for GET request - params are in URL
-    [](bool success, uint16_t httpStatus, String error) {
-      if (success) {
-        Serial.printf("✅ WhatsApp message sent! HTTP Status: %d\n", httpStatus);
+    [isO2Alarm](const painlessmesh::InternetResult& result) {
+      alertInFlight = false;
+      const auto reply = callmebot::judge(result.httpStatus, result.response);
+      if (reply.accepted) {
+        Serial.printf("✅ WhatsApp message queued by CallMeBot (request %u, HTTP %u, %u attempt(s))\n",
+                      result.messageId, result.httpStatus, result.attempts);
       } else {
-        Serial.printf("❌ Failed to send WhatsApp: %s (HTTP: %d)\n", error.c_str(), httpStatus);
+        Serial.printf("❌ WhatsApp message not sent (request %u): %s\n",
+                      result.messageId, reply.meaning);
+        Serial.printf("   HTTP %u after %u attempt(s)\n", result.httpStatus, result.attempts);
+        if (result.error.length() > 0) {
+          Serial.printf("   Error: %s\n", result.error.c_str());
+        }
+        if (result.response.length() > 0) {
+          Serial.printf("   CallMeBot said: %s\n", result.response.c_str());
+        }
+      }
+      if (reply.holdOffMs > alertHoldMs) {
+        alertHoldMs = reply.holdOffMs;
+      }
+      // An alarm CallMeBot did not take is still an alarm nobody has seen:
+      // re-arm it, so a later reading sends it again once the pause is over.
+      if (isO2Alarm && !reply.accepted) {
+        o2Alarm = false;
       }
     },
     static_cast<uint8_t>(painlessmesh::gateway::GatewayPriority::PRIORITY_HIGH)
   );
-  
+
   if (msgId > 0) {
-    Serial.printf("   Message queued with ID: %u\n", msgId);
-  } else {
-    Serial.println("   ❌ Failed to queue message - no gateway available");
+    Serial.printf("   Handed to the mesh as request %u; the result follows when the gateway answers\n", msgId);
+    return true;
   }
+  // The callback reports why, from the scheduler, in a moment.
+  Serial.println("   Not handed to the mesh");
+  return false;
 }
 
 /**
@@ -243,7 +309,10 @@ void sendSensorDataToCloud() {
   // Simulate sensor readings using configured ranges
   float temperature = TEMP_MIN + random(0, (int)(TEMP_RANGE * 10)) / 10.0;
   float humidity = HUMIDITY_MIN + random(0, (int)(HUMIDITY_RANGE * 10)) / 10.0;
-  float o2Level = O2_MIN + random(0, (int)(O2_RANGE * 10)) / 10.0;
+  // O2 drifts rather than jumping, so an alarm is an episode, not a coin toss
+  o2Level += random(-3, 4) / 10.0;
+  if (o2Level < O2_MIN) o2Level = O2_MIN;
+  if (o2Level > O2_MAX) o2Level = O2_MAX;
   
   // Create JSON payload
   String payload = "{";
@@ -257,11 +326,15 @@ void sendSensorDataToCloud() {
   Serial.println("\n📊 Sending sensor data to cloud...");
   Serial.printf("   Payload: %s\n", payload.c_str());
   
-  // Check for alarm conditions using configured threshold
-  if (o2Level < O2_ALARM_THRESHOLD) {
-    // O2 level critical - send WhatsApp alert!
+  // Alert once when O2 falls below the threshold; re-arm once it recovers.
+  // An alert that could not be sent (no gateway yet, paused after a refusal)
+  // is tried again at the next reading while the alarm lasts.
+  if (!o2Alarm && o2Level < O2_ALARM_THRESHOLD) {
     String alertMsg = "⚠️ ALARM: O2 level critical at " + String(o2Level, 1) + " mg/L! Node: " + String(mesh.getNodeId());
-    sendAlertToWhatsApp(alertMsg);
+    o2Alarm = sendAlertToWhatsApp(alertMsg, true);
+  } else if (o2Alarm && o2Level > O2_ALARM_CLEAR) {
+    Serial.printf("   O2 back to %.1f mg/L; alarm cleared\n", o2Level);
+    o2Alarm = false;
   }
   
   // Only send if Internet is available
@@ -299,7 +372,7 @@ void sendSensorDataToCloud() {
 /**
  * Send the startup notification once a gateway with Internet is known.
  *
- * Runs every 30 s from taskStartupAlert until it has handed the message to
+ * Runs every 30 s from taskStartupAlert until the message has been handed to
  * sendToInternet(), then disables itself.
  */
 void sendStartupAlert() {
@@ -307,8 +380,9 @@ void sendStartupAlert() {
     Serial.println("(startup WhatsApp waiting for a gateway with Internet; retrying in 30 s)");
     return;
   }
-  sendAlertToWhatsApp(startupMsg);
-  taskStartupAlert.disable();
+  if (sendAlertToWhatsApp(startupMsg)) {
+    taskStartupAlert.disable();
+  }
 }
 
 void receivedCallback(uint32_t from, String& msg) {
@@ -386,7 +460,11 @@ void setup() {
   // First attempt in 30 s, then every 30 s until a gateway with Internet is
   // known: a bridge can use its own uplink at once, a regular node has to
   // find the mesh first.
-  startupMsg = "🚀 Node " + String(mesh.getNodeId()) + " started!";
+  // A boot tag makes every start's text different: a service that drops a
+  // repeat of the last message (or answers it with HTTP 208) will not
+  // swallow this one because the previous boot sent the same words.
+  startupMsg = "🚀 Node " + String(mesh.getNodeId()) + " started (boot " +
+               String((uint32_t)random(0x10000), HEX) + ")";
   Serial.println("Will send the startup WhatsApp as soon as a gateway with Internet is known (first try in 30 s)...\n");
   userScheduler.addTask(taskStartupAlert);
   taskStartupAlert.enableDelayed();

package/library.json

@@ -6,7 +6,7 @@
     "type": "git",
     "url": "https://github.com/Alteriom/painlessMesh"
   },
-  "version": "2.0.3",
+  "version": "2.1.0",
   "frameworks": [
     "arduino"
   ],

package/library.properties

@@ -1,5 +1,5 @@
 name=Alteriom PainlessMesh
-version=2.0.3
+version=2.1.0
 author=Coopdis,Scotty Franzyshen,Edwin van Leeuwen,Germán Martín,Maximilian Schwarz,Doanh Doanh,Alteriom
 maintainer=Alteriom
 sentence=A painless way to setup a mesh with ESP8266 and ESP32 devices with Alteriom extensions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alteriom/painlessmesh",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "description": "painlessMesh is a user-friendly library for creating mesh networks with ESP8266 and ESP32 devices. This Alteriom fork includes additional packages for sensor data (SensorPackage), device commands (CommandPackage), and status monitoring (StatusPackage). It handles routing and network management automatically, so you can focus on your application. The library uses JSON-based messaging and syncs time across all nodes, making it ideal for coordinated behaviour like synchronized light displays or sensor networks reporting to a central node.",
   "keywords": [
     "arduino",

package/src/AlteriomPainlessMesh.h

@@ -29,10 +29,10 @@
 /**
  * @brief AlteriomPainlessMesh library version information
  */
-#define ALTERIOM_PAINLESS_MESH_VERSION "2.0.3"
+#define ALTERIOM_PAINLESS_MESH_VERSION "2.1.0"
 #define ALTERIOM_PAINLESS_MESH_VERSION_MAJOR 2
-#define ALTERIOM_PAINLESS_MESH_VERSION_MINOR 0
-#define ALTERIOM_PAINLESS_MESH_VERSION_PATCH 3
+#define ALTERIOM_PAINLESS_MESH_VERSION_MINOR 1
+#define ALTERIOM_PAINLESS_MESH_VERSION_PATCH 0
 
 /**
  * @brief Library description and usage information

package/src/arduino/wifi.hpp

@@ -2727,41 +2727,44 @@ class Mesh : public painlessmesh::Mesh<Connection> {
 
 #if defined(ESP32) || defined(ESP8266)
   /**
-   * Read the start of an HTTP response body, bounded in bytes and in time
-   *
-   * The gateway used to discard the body, so a service that answers a refusal
-   * with a 2xx (CallMeBot, issue #450) was reported as delivered, and a
-   * failure reached the origin node as a bare status. When the length is
-   * known and small the whole body is taken; otherwise up to maxBytes are
-   * read from the stream, waiting at most GATEWAY_RESPONSE_HEAD_TIMEOUT_MS,
-   * which keeps a large or chunked page from eating the heap or the
-   * cooperative scheduler.
+   * The start and the end of the response body (gateway::ResponseExcerpt),
+   * read from the stream for at most GATEWAY_RESPONSE_HEAD_TIMEOUT_MS and
+   * GATEWAY_RESPONSE_SCAN_BYTES. A body that fits whole is read whole. A
+   * chunked body is read through gateway::ChunkedBodyDecoder: the raw stream
+   * carries the framing, which getString() would remove but only by keeping
+   * the whole body.
    */
-  static TSTRING readResponseHead(HTTPClient& http, size_t maxBytes) {
+  static TSTRING readResponseExcerpt(HTTPClient& http) {
     const int size = http.getSize();
-    if (size >= 0 && static_cast<size_t>(size) <= maxBytes) {
+    if (size >= 0 &&
+        static_cast<size_t>(size) <=
+            gateway::GATEWAY_RESPONSE_HEAD_BYTES + gateway::GATEWAY_RESPONSE_TAIL_BYTES) {
       return http.getString();
     }
-    TSTRING head;
+    gateway::ResponseExcerpt excerpt;
     WiFiClient* stream = http.getStreamPtr();
-    if (stream == nullptr) return head;
+    if (stream == nullptr) return excerpt.text();
+    const bool chunked =
+        size < 0 && gateway::transferEncodingIsChunked(http.header("Transfer-Encoding"));
+    gateway::ChunkedBodyDecoder decoder(excerpt);
     const uint32_t deadline =
         millis() + gateway::GATEWAY_RESPONSE_HEAD_TIMEOUT_MS;
-    while (head.length() < maxBytes &&
-           static_cast<int32_t>(deadline - millis()) > 0) {
+    bool more = true;
+    while (more && static_cast<int32_t>(deadline - millis()) > 0) {
       int available = stream->available();
       if (available <= 0) {
         if (!stream->connected()) break;
         delay(1);
         continue;
       }
-      while (available-- > 0 && head.length() < maxBytes) {
+      while (more && available-- > 0) {
         const int c = stream->read();
         if (c < 0) break;
-        head += static_cast<char>(c);
+        more = chunked ? decoder.add(static_cast<char>(c))
+                       : excerpt.add(static_cast<char>(c));
       }
     }
-    return head;
+    return excerpt.text();
   }
 #endif
 
@@ -2836,8 +2839,13 @@ class Mesh : public painlessmesh::Mesh<Connection> {
           // that genuinely stopped answering NODE_SYNC still gets reaped even
           // under continuous gateway traffic from other peers.
           const auto blockingStartedMs = millis();
+          // `retryable` is the gateway's word to the origin node on whether
+          // the identical request may be sent again: 0 whenever it may have
+          // reached the server, so a retry cannot deliver it twice.
           auto finish = [this, &pkg, ingress, blockingStartedMs](
-                            bool ok, uint16_t code, const TSTRING& err) {
+                            bool ok, uint16_t code, const TSTRING& err,
+                            int8_t retryable, const TSTRING& response = TSTRING(),
+                            uint32_t retryAfterMs = 0) {
             const auto stalledMs = millis() - blockingStartedMs;
             auto refreshed = gateway::refreshPeerWatchdogs(*this, stalledMs);
             if (refreshed > 0) {
@@ -2847,27 +2855,28 @@ class Mesh : public painlessmesh::Mesh<Connection> {
                   static_cast<unsigned>(refreshed),
                   static_cast<unsigned long>(stalledMs));
             }
-            this->sendGatewayAck(pkg, ok, code, err, ingress);
+            this->sendGatewayAck(pkg, ok, code, err, ingress, response, retryable,
+                                 retryAfterMs);
           };
 
           // Check Internet connectivity
           // First check WiFi status for quick fail
           if (WiFi.status() != WL_CONNECTED) {
-            finish(false, 0, "Gateway WiFi not connected");
+            finish(false, 0, "Gateway WiFi not connected", 0);
             return true;  // Consume package - we handled it (with error)
           }
           
           // Then check actual internet access (DNS resolution)
           // This detects when WiFi is connected but router has no internet
           if (!hasActualInternetAccess()) {
-            finish(false, 0, "Router has no internet access - check WAN connection");
+            finish(false, 0, "Router has no internet access - check WAN connection", 0);
             return true;  // Consume package - we handled it (with error)
           }
           
           // Finally, check for captive portal interference
           // This detects when DNS works but HTTP requests are intercepted
           if (!detectCaptivePortal()) {
-            finish(false, 0, "Captive portal detected - requires web authentication. Check router/WiFi settings");
+            finish(false, 0, "Captive portal detected - requires web authentication. Check router/WiFi settings", 0);
             return true;  // Consume package - we handled it (with error)
           }
 
@@ -2899,7 +2908,7 @@ class Mesh : public painlessmesh::Mesh<Connection> {
                            (gateway::GATEWAY_DNS_NEGATIVE_TTL_MS - failedAgoMs) /
                            1000));
               Log(ERROR, "%s\n", dnsBuf);
-              finish(false, 0, TSTRING(dnsBuf));
+              finish(false, 0, TSTRING(dnsBuf), 0);
               return true;
             }
             IPAddress resolved;
@@ -2909,7 +2918,7 @@ class Mesh : public painlessmesh::Mesh<Connection> {
               snprintf(dnsBuf, sizeof(dnsBuf), "DNS lookup failed for %s",
                        host.c_str());
               Log(ERROR, "%s\n", dnsBuf);
-              finish(false, 0, TSTRING(dnsBuf));
+              finish(false, 0, TSTRING(dnsBuf), 0);
               return true;
             }
           }
@@ -2959,6 +2968,17 @@ class Mesh : public painlessmesh::Mesh<Connection> {
 #endif
           }
 
+          // The same id on every attempt at this call. A service that
+          // honours Idempotency-Key treats a retry as the request it already
+          // has; anything recording requests can count the copies.
+          const TSTRING requestId =
+              gateway::requestIdFor(pkg.originNode, pkg.messageId, pkg.requestNonce);
+          http.addHeader("X-Request-Id", requestId.c_str());
+          http.addHeader("Idempotency-Key", requestId.c_str());
+          // Not const: both cores declare collectHeaders(const char* keys[], ...).
+          const char* collected[] = {"Retry-After", "Transfer-Encoding"};
+          http.collectHeaders(collected, 2);
+
           // Make request (GET if no payload, POST if payload)
           if (pkg.payload.length() > 0) {
             http.addHeader("Content-Type", pkg.contentType.c_str());
@@ -2967,11 +2987,11 @@ class Mesh : public painlessmesh::Mesh<Connection> {
             httpCode = http.GET();
           }
 
-          // A 2xx is the origin's acceptance, except 203 (a proxy transformed
-          // the response) and except when the body says the service refused
-          // the request: CallMeBot answers "Too many requests" under 201 and
-          // 203 (issue #450). The body is therefore read -- bounded -- before
-          // classifying, and it is what the origin node is told on failure.
+          // HTTP semantics only: 200/201/202/204 succeed, anything else fails,
+          // and a retry is allowed only when it cannot deliver the request
+          // twice (see gateway::classifyHttpResult). Whether a service's reply
+          // means what the application wanted is the application's decision,
+          // so the start of the body goes back on success as well as failure.
           //
           // 3xx redirects are not automatically followed.
           //
@@ -2981,72 +3001,68 @@ class Mesh : public painlessmesh::Mesh<Connection> {
           TSTRING responseHead;
           if (httpCode > 0) {
             responseHead =
-                readResponseHead(http, gateway::GATEWAY_RESPONSE_HEAD_BYTES);
+                readResponseExcerpt(http);
           }
           const auto outcome =
               gateway::classifyHttpResult(httpCode, responseHead);
           success = outcome.success;
+          const TSTRING responseSummary =
+              httpCode > 0 ? gateway::summarizeResponseBody(responseHead) : TSTRING();
+          uint32_t retryAfterMs = 0;
+          if (outcome.retryable && httpCode > 0) {
+            retryAfterMs = gateway::parseRetryAfterMs(http.header("Retry-After"));
+          }
 
           if (!outcome.transportError) {
-            char errorBuf[192];
+            char errorBuf[320];
             const char* reason = outcome.reason.c_str();
             const char* sep = outcome.reason.length() > 0 ? ": " : "";
             if (success) {
               Log(COMMUNICATION, "HTTP request completed: code=%d\n", httpCode);
-            } else if (outcome.refusedByBody) {
-              // Success-class status, refusing body. Not retryable: the
-              // service answered, and the origin node gets its words.
-              snprintf(errorBuf, sizeof(errorBuf),
-                       "HTTP %d: service refused the request%s%s", httpCode,
-                       sep, reason);
-              error = TSTRING(errorBuf);
-              Log(ERROR, "HTTP request refused by the service: %s\n", errorBuf);
             } else if (outcome.unverifiedStatus) {
-              // A 2xx outside 200/201/202/204. CallMeBot answers 208 to a
-              // message that never arrives (issue #452), so this is a
-              // failure, and the body -- the only place the service says
-              // what it did -- goes to the origin node and to the log at
-              // ERROR level, where a sketch running the default levels
-              // sees it. 203 stays retryable; the rest are final.
+              // A 2xx outside 200/201/202/204: the server answered, but not
+              // with a status this library can call a delivery. Never
+              // retried. Logged at ERROR, where a sketch on the default
+              // levels sees what the service said.
               snprintf(errorBuf, sizeof(errorBuf),
                        "HTTP %d: not a delivery the gateway can confirm%s%s",
                        httpCode, sep, reason);
               error = TSTRING(errorBuf);
               Log(ERROR, "HTTP response unverified: %s\n", errorBuf);
-            } else if (httpCode >= 500 && httpCode < 600) {
-              // 5xx server errors are retryable, log at COMMUNICATION level
+            } else if (outcome.retryable) {
+              // 429 or 503: the server says it did not take the request.
               snprintf(errorBuf, sizeof(errorBuf), "HTTP %d%s%s", httpCode, sep,
                        reason);
               error = TSTRING(errorBuf);
-              Log(COMMUNICATION, "HTTP server error: code=%d (will retry)\n", httpCode);
-            } else if (httpCode == 429) {
-              // HTTP 429 rate limit is retryable, log at COMMUNICATION level
-              snprintf(errorBuf, sizeof(errorBuf), "HTTP %d%s%s", httpCode, sep,
-                       reason);
-              error = TSTRING(errorBuf);
-              Log(COMMUNICATION, "HTTP rate limit: code=%d (will retry)\n", httpCode);
+              Log(COMMUNICATION, "HTTP %d: the server asked to retry (after %lu ms)\n",
+                  httpCode, static_cast<unsigned long>(retryAfterMs));
             } else {
-              // 1xx, 3xx, 4xx (except 429) - non-retryable, log at ERROR level
               snprintf(errorBuf, sizeof(errorBuf), "HTTP %d%s%s", httpCode, sep,
                        reason);
               error = TSTRING(errorBuf);
               Log(ERROR, "HTTP request failed: %s\n", errorBuf);
             }
           } else {
-            // Network errors (httpCode <= 0) are retryable but indicate serious issues
-            // Keep at ERROR level as they may indicate gateway connectivity problems
+            // Below HTTP. When the request may already be at the server -- a
+            // read timeout, a connection lost after sending -- it is not
+            // retried, and the error says why, so an application that
+            // resends does so knowing it may duplicate.
             error = http.errorToString(httpCode);
+            if (!outcome.retryable) {
+              error += " (the request may have reached the server; not retried)";
+            }
             Log(ERROR, "HTTP request failed: %s\n", error.c_str());
           }
 
           http.end();
 
-          // Send acknowledgment back. Transport errors carry status 0, the
-          // value handleGatewayAck() treats as a retryable network error.
-          finish(success, outcome.ackStatus, error);
+          // Send acknowledgment back, with the verdict on retrying and the
+          // start of whatever the server said.
+          finish(success, outcome.ackStatus, error, outcome.retryable ? 1 : 0,
+                 responseSummary, retryAfterMs);
 #else
         // Non-ESP platform - send error
-        finish(false, 0, "HTTP client not available on this platform");
+        finish(false, 0, "HTTP client not available on this platform", 0);
 #endif
 
           return true;  // Consume package - we have processed it and sent

package/src/painlessMeshSTA.cpp

@@ -628,6 +628,9 @@ void ICACHE_FLASH_ATTR StationScan::connectToAP() {
 #endif
   bool isRooted = layout::isRooted(mesh->asNodeTree());
   if (isRooted) everRooted = true;
+  // The immediate-rescan allowance is per outage, and this is the one place
+  // every scan passes through: a node with a connection has not spent it.
+  if (painlessmesh::layout::liveSubs(*mesh) > 0) rejoinScanned = false;
   if (aps.empty()) {
     // No unknown nodes found
     consecutiveEmptyScans++;
@@ -732,11 +735,42 @@ void ICACHE_FLASH_ATTR StationScan::connectToAP() {
       task.delay(interval);
       if (orphanScanBackoff < 2) orphanScanBackoff++;
     } else {
-      // else scan fast (SCAN_INTERVAL)
-      Log(CONNECTION,
-          "connectToAP(): No unknown nodes found scan rate set to "
-          "fast\n");
+      // Not connected, and this scan turned up nothing to connect to.
+      //
+      // "Fast" here is 0.5 * SCAN_INTERVAL -- fifteen seconds. For a node
+      // that still has a live connection (an AP-side child) that is soon
+      // enough: it is in the mesh and reachable while it looks for more.
+      // For a node with none it is the whole cost of the outage, and it is
+      // paid while the node's neighbours still have it in their routing
+      // tables: they keep sending to it until their own NODE_TIMEOUT, and
+      // those messages are dropped.
+      //
+      // Measured on the Alteriom HIL rig (issue #459): an ESP32-C3 closed
+      // its only uplink on a momentary nodeSync contradiction, logged
+      // "scan rate set to fast" 12 ms later, and did not scan again for
+      // exactly 15 000 ms. It was out of the mesh for 16.2 s and answered
+      // an empty node list throughout; a unicast sent to it in that window
+      // was accepted by the sender and lost. The scan that finally ran
+      // found five mesh APs at -30 to -58 dBm and was associated 1.2 s
+      // later. There was nothing to wait for.
+      //
+      // So a node with no connections left scans at once. Once per outage:
+      // `rejoinScanned` is cleared as soon as it has a connection again,
+      // so a node that is simply alone falls back to the interval instead
+      // of scanning back to back.
       task.setInterval(0.5 * SCAN_INTERVAL);
+      if (painlessmesh::layout::liveSubs(*mesh) == 0 && !rejoinScanned) {
+        rejoinScanned = true;
+        Log(CONNECTION,
+            "connectToAP(): No connections left; scanning again now rather "
+            "than in %d s\n",
+            (int)(0.5 * SCAN_INTERVAL / TASK_SECOND));
+        task.forceNextIteration();
+      } else {
+        Log(CONNECTION,
+            "connectToAP(): No unknown nodes found scan rate set to "
+            "fast\n");
+      }
     }
     mesh->stability += min(1000 - mesh->stability, (size_t)25);
   } else {