@alteriom/painlessmesh 2.0.1 → 2.0.3

package/src/painlessmesh/gateway.hpp

@@ -568,6 +568,8 @@ class InternetHealthChecker {
    * @return true if connection succeeded
    */
   bool checkNow() {
+    // A full probe answers the question the on-demand budget exists for.
+    onDemandSpent_ = false;
     status_.checkCount++;
     status_.lastCheckTime = millis();
 
@@ -592,6 +594,27 @@ class InternetHealthChecker {
     return connected;
   }
 
+  /**
+   * @brief Probe once outside the schedule, for a caller that needs the
+   *        answer now (issue #450)
+   *
+   * A bridge's first periodic probe runs while its station is still
+   * associating and fails, and the next is a full interval away. A send in
+   * that window may spend one extra probe to learn that the uplink has come
+   * up since. One: the probe is a blocking connect with a timeout, so the
+   * budget is a single on-demand probe per periodic one. A node whose uplink
+   * really is down pays it once per interval, not on every call.
+   *
+   * @return true if Internet is reachable now
+   */
+  bool checkOnDemand() {
+    if (status_.available) return true;
+    if (onDemandSpent_) return false;
+    const bool connected = checkNow();
+    onDemandSpent_ = true;
+    return connected;
+  }
+
   /**
    * @brief Get check interval
    * @return Check interval in milliseconds
@@ -667,6 +690,13 @@ class InternetHealthChecker {
     status_.lastError = "Mock: No Internet in test environment";
     return false;
 #elif defined(ESP32) || defined(ESP8266)
+    // No station, no uplink: answer at once instead of spending the connect
+    // timeout on a link that does not exist. This is what keeps the
+    // on-demand probe cheap on a bridge whose router is down.
+    if (WiFi.status() != WL_CONNECTED) {
+      status_.lastError = "Station not connected";
+      return false;
+    }
     WiFiClient client;
     uint32_t started = millis();
 #ifdef ESP32
@@ -704,6 +734,7 @@ class InternetHealthChecker {
   // State
   InternetStatus status_;
   InternetChangedCallback_t connectivityChangedCallback_;
+  bool onDemandSpent_ = false;
 
 #ifdef PAINLESSMESH_BOOST
   bool mockConnected_ = false;
@@ -965,6 +996,301 @@ class GatewayDataPackage : public plugin::SinglePackage {
 
 };
 
+/**
+ * @brief The outcome of a gateway HTTP request, classified for the ack
+ *
+ * HTTPClient::GET()/POST() return an int with two distinct meanings: a
+ * positive value is an HTTP status code from the destination, while a
+ * negative value is one of the client's own transport errors (HTTPC_ERROR_*,
+ * e.g. -1 for a refused connection or -11 for a read timeout). Zero is not
+ * produced by either.
+ *
+ * GatewayAckPackage::httpStatus is a uint16_t, so a negative code cannot be
+ * forwarded as-is. Transport errors are reported as httpStatus 0, which is
+ * what Mesh::handleGatewayAck() already treats as a retryable network error;
+ * the human-readable cause travels in GatewayAckPackage::error instead.
+ */
+struct HttpRequestOutcome {
+  /** True only for status codes that indicate genuine delivery. */
+  bool success = false;
+
+  /** Value to place in GatewayAckPackage::httpStatus (0 for transport errors). */
+  uint16_t ackStatus = 0;
+
+  /** True when the client failed before any HTTP status was received. */
+  bool transportError = false;
+
+  /**
+   * True when the status was success-class but the response body said the
+   * service refused the request (issue #450).
+   */
+  bool refusedByBody = false;
+
+  /**
+   * True for a 2xx the gateway cannot vouch for: anything but 200, 201, 202
+   * and 204. CallMeBot answers HTTP 208 to a message that never arrives
+   * (issue #452), so a status outside the verified set is reported as a
+   * failure that carries the body, never as a delivery.
+   */
+  bool unverifiedStatus = false;
+
+  /**
+   * One-line reason for a failure, taken from the response body when there
+   * is one; empty on success. Sized to fit a GatewayAckPackage::error.
+   */
+  TSTRING reason;
+};
+
+/** Longest response-body excerpt carried in an acknowledgment error. */
+static const size_t GATEWAY_RESPONSE_REASON_MAX = 120;
+
+/**
+ * How much of a response body the gateway reads for classification and for
+ * the error it reports. Enough for a service's one-line verdict, small enough
+ * that an HTML error page cannot eat an ESP8266's heap.
+ */
+static const size_t GATEWAY_RESPONSE_HEAD_BYTES = 512;
+
+/** How long the gateway waits for that head to arrive after the status. */
+static const uint32_t GATEWAY_RESPONSE_HEAD_TIMEOUT_MS = 250;
+
+inline bool responseContains(const TSTRING& haystack, const char* needle) {
+#if defined(PAINLESSMESH_BOOST)
+  return haystack.find(needle) != std::string::npos;
+#else
+  return haystack.indexOf(needle) >= 0;
+#endif
+}
+
+/**
+ * @brief Reduce a response body to one line fit for a log or an error string
+ *
+ * Tags are dropped, whitespace collapsed and the result cut at maxLen with an
+ * ellipsis, so an HTML error page reads "Oops! Too many requests... You have
+ * called to the API to often." in a serial log instead of markup.
+ */
+inline TSTRING summarizeResponseBody(
+    const TSTRING& body, size_t maxLen = GATEWAY_RESPONSE_REASON_MAX) {
+  TSTRING out;
+  bool inTag = false;
+  bool pendingSpace = false;
+  for (size_t i = 0; i < body.length(); ++i) {
+    const char c = body[i];
+    if (c == '<') {
+      inTag = true;
+      continue;
+    }
+    if (c == '>') {
+      inTag = false;
+      pendingSpace = true;
+      continue;
+    }
+    if (inTag) continue;
+    if (c == ' ' || c == '\t' || c == '\r' || c == '\n') {
+      pendingSpace = true;
+      continue;
+    }
+    if (pendingSpace && out.length() > 0) out += ' ';
+    pendingSpace = false;
+    out += c;
+    if (out.length() >= maxLen) {
+      out += "...";
+      break;
+    }
+  }
+  return out;
+}
+
+/**
+ * @brief Does a success-class response body say the service refused the request?
+ *
+ * Some services answer a refusal with a 2xx. CallMeBot's WhatsApp API, which
+ * the sendToInternet example integrates, returns its "Too many requests" page
+ * under HTTP 201 and HTTP 203 (issue #450). The phrases are the ones seen
+ * from services this library's examples target, and they are deliberately
+ * specific: a JSON payload that merely contains the word "error" is not a
+ * refusal.
+ */
+inline bool responseBodyRefuses(const TSTRING& body) {
+  static const char* const REFUSALS[] = {"Too many requests", "Oops!"};
+  for (const char* phrase : REFUSALS) {
+    if (responseContains(body, phrase)) return true;
+  }
+  return false;
+}
+
+/**
+ * @brief Classify an HTTPClient result for the gateway acknowledgment
+ *
+ * A transport error (rawCode <= 0) is neither success nor an HTTP status.
+ * Only 200, 201, 202 and 204 count as delivery on the status alone, and even
+ * those are overturned by a body that says the service refused the request:
+ * CallMeBot answers "Too many requests" under 201 and 203 (issue #450). Any
+ * other 2xx is unverified. 203 means a proxy transformed the reply; 208 is
+ * what CallMeBot answers to a message that never arrives (issue #452); none
+ * of them is a delivery this library can vouch for, so they are failures
+ * that carry the body. Every failure's reason is a one-line excerpt of the
+ * body when there is one, so the origin node learns why and not only a
+ * number.
+ *
+ * @param rawCode The int returned by HTTPClient::GET() or ::POST()
+ * @param body The start of the response body, empty if none was read
+ * @return Classified outcome, safe to place in a GatewayAckPackage
+ */
+inline HttpRequestOutcome classifyHttpResult(int rawCode,
+                                             const TSTRING& body = TSTRING()) {
+  HttpRequestOutcome outcome;
+  if (rawCode <= 0) {
+    outcome.transportError = true;
+    return outcome;
+  }
+  outcome.ackStatus =
+      static_cast<uint16_t>(rawCode > 0xFFFF ? 0xFFFF : rawCode);
+  const bool verified =
+      rawCode == 200 || rawCode == 201 || rawCode == 202 || rawCode == 204;
+  if (verified && responseBodyRefuses(body)) {
+    outcome.refusedByBody = true;
+    outcome.reason = summarizeResponseBody(body);
+    return outcome;
+  }
+  outcome.success = verified;
+  if (!verified) {
+    outcome.unverifiedStatus = rawCode >= 200 && rawCode < 300;
+    outcome.reason = summarizeResponseBody(body);
+  }
+  return outcome;
+}
+
+/**
+ * The phrase a node puts in a failed GATEWAY_ACK when it received a gateway
+ * request but serves none: a bridge that rebooted, crashed or was reflashed
+ * as a regular node announces nothing, and its peers keep routing Internet
+ * requests to it until its last bridge status ages out. The origin node
+ * recognises the phrase, forgets that node as a gateway, and retries through
+ * the next one. Changing it breaks that recognition across a mixed fleet.
+ */
+static const char GATEWAY_NOT_A_GATEWAY_PHRASE[] = "is not an Internet gateway";
+
+/**
+ * How long a destination whose name failed to resolve is refused without
+ * another lookup (issue #453). On ESP32 a DNS lookup has no timeout this
+ * library can set, so a dead name stalls the cooperative scheduler for the
+ * resolver's own patience; once a minute is survivable, once per attempt --
+ * with the origin node retrying and the bridge's own sends adding theirs --
+ * was not. On ESP8266 the core bounds HTTPClient's own lookup by the HTTP
+ * timeout, so the gateway performs no separate lookup there and this cache
+ * is never fed.
+ */
+static const uint32_t GATEWAY_DNS_NEGATIVE_TTL_MS = 60000;
+
+/**
+ * @brief The host of an http(s) URL, without scheme, port, path or query
+ *
+ * "https://api.example.com:8443/x?y" -> "api.example.com". Empty when the
+ * URL has no host.
+ */
+inline TSTRING hostFromUrl(const TSTRING& url) {
+  const char* s = url.c_str();
+  const size_t n = url.length();
+  size_t i = 0;
+  for (size_t k = 0; k + 2 < n; ++k) {
+    if (s[k] == ':' && s[k + 1] == '/' && s[k + 2] == '/') {
+      i = k + 3;
+      break;
+    }
+  }
+  size_t j = i;
+  while (j < n && s[j] != '/' && s[j] != '?' && s[j] != '#' && s[j] != ':') ++j;
+  TSTRING host;
+  for (size_t k = i; k < j; ++k) host += s[k];
+  return host;
+}
+
+/** True for a dotted-decimal IPv4 literal, which needs no DNS. */
+inline bool looksLikeIpLiteral(const TSTRING& host) {
+  if (host.length() == 0) return false;
+  for (size_t i = 0; i < host.length(); ++i) {
+    const char c = host[i];
+    if (!(c >= '0' && c <= '9') && c != '.') return false;
+  }
+  return true;
+}
+
+/**
+ * @brief A few hosts that recently failed to resolve, and when
+ *
+ * Small and fixed: a gateway talks to a handful of destinations. A host is
+ * remembered with a TTL; while it is within it, isFailing() says so and the
+ * caller answers the request without a lookup.
+ */
+class NegativeDnsCache {
+ public:
+  // An enum, not a static const member: the test suite passes it to Catch2 by
+  // reference, which needs a definition C++14 cannot give an in-class
+  // constant without an out-of-line one.
+  enum : size_t { SLOTS = 4 };
+
+  void remember(const TSTRING& host, uint32_t nowMs,
+                uint32_t ttlMs = GATEWAY_DNS_NEGATIVE_TTL_MS) {
+    Entry* slot = find(host);
+    if (slot == nullptr) {
+      slot = &entries_[0];
+      for (size_t i = 0; i < SLOTS; ++i) {
+        if (!entries_[i].used) {
+          slot = &entries_[i];
+          break;
+        }
+        if (static_cast<int32_t>(entries_[i].at - slot->at) < 0) slot = &entries_[i];
+      }
+    }
+    slot->used = true;
+    slot->host = host;
+    slot->at = nowMs;
+    slot->ttl = ttlMs;
+  }
+
+  /** Is `host` inside its negative TTL? `ageMs` receives how long ago it failed. */
+  bool isFailing(const TSTRING& host, uint32_t nowMs, uint32_t* ageMs = nullptr) {
+    Entry* slot = find(host);
+    if (slot == nullptr) return false;
+    const uint32_t age = nowMs - slot->at;
+    if (age >= slot->ttl) {
+      slot->used = false;
+      return false;
+    }
+    if (ageMs != nullptr) *ageMs = age;
+    return true;
+  }
+
+  void forget(const TSTRING& host) {
+    Entry* slot = find(host);
+    if (slot != nullptr) slot->used = false;
+  }
+
+  size_t size() const {
+    size_t n = 0;
+    for (size_t i = 0; i < SLOTS; ++i) n += entries_[i].used ? 1 : 0;
+    return n;
+  }
+
+ private:
+  struct Entry {
+    TSTRING host;
+    uint32_t at = 0;
+    uint32_t ttl = 0;
+    bool used = false;
+  };
+
+  Entry* find(const TSTRING& host) {
+    for (size_t i = 0; i < SLOTS; ++i) {
+      if (entries_[i].used && entries_[i].host == host) return &entries_[i];
+    }
+    return nullptr;
+  }
+
+  Entry entries_[SLOTS];
+};
+
 /**
  * @brief Gateway Acknowledgment Package for delivery confirmations
  *
@@ -1214,13 +1540,15 @@ class GatewayAckPackage : public plugin::SinglePackage {
  * GATEWAY_DNS_TIMEOUT_MS on ESP8266, skipped on ESP32) runs before them
  * whenever the GATEWAY_CONNECTIVITY_CACHE_MS window has expired.
  *
- * @warning One residual is not in this budget: the HTTP calls resolve their
- *          hostnames inside the platform core before their socket timeout
- *          applies, and on ESP32 that in-request resolver wait is not
- *          separately boundable in the cores this library targets. On a
- *          network with blackholed DNS the request path can therefore still
- *          exceed this ceiling on ESP32. See SECURITY.md "Gateway blocking:
- *          the mesh partition risk".
+ * @warning One residual is not in this budget: hostname resolution on ESP32
+ *          is not separately boundable in the cores this library targets.
+ *          Since issue #453 the handler performs that lookup itself on
+ *          ESP32 and remembers a failure for GATEWAY_DNS_NEGATIVE_TTL_MS, so
+ *          on a network with blackholed DNS the request path can still
+ *          exceed this ceiling on ESP32, but at most once per TTL per
+ *          destination host rather than once per attempt. On ESP8266 the
+ *          core bounds HTTPClient's own lookup by the HTTP timeout. See
+ *          SECURITY.md "Gateway blocking: the mesh partition risk".
  */
 constexpr unsigned long gatewayBlockingBudgetMs() {
   return 2UL * static_cast<unsigned long>(GATEWAY_HTTP_TIMEOUT_MS) +

package/src/painlessmesh/logger.hpp

@@ -30,6 +30,19 @@ typedef enum {
   DEBUG = 1 << 11
 } LogLevel;
 
+// Log() is printf-like. In the desktop test build the compiler is told so,
+// and -Wall -Werror in CI then rejects any argument that does not match its
+// specifier. That class of bug reached main twice in routePackage(): size_t
+// through %d/%u, and a DeserializationError object through %u (CodeQL
+// cpp/wrong-type-format-argument). The check is kept to the desktop build on
+// purpose: ESP-IDF 5 makes uint32_t `unsigned long`, so on ESP32 every %u of
+// a node id would warn, harmlessly, in every user's build.
+#if defined(PAINLESSMESH_BOOST) && defined(__GNUC__)
+#define PAINLESSMESH_LOG_FORMAT __attribute__((format(printf, 3, 4)))
+#else
+#define PAINLESSMESH_LOG_FORMAT
+#endif
+
 class LogClass {
  public:
   // Where messages go instead of Serial. The sketch owns framing: on a board
@@ -83,7 +96,7 @@ class LogClass {
     Serial.println();
     return;
   }
-  void operator()(LogLevel type, const char *format...) {
+  void operator()(LogLevel type, const char *format...) PAINLESSMESH_LOG_FORMAT {
     if (type & types) {  // Print only the message types set for output
       va_list args;
       va_start(args, format);