@alteriom/painlessmesh 1.9.20 → 2.0.0

package/src/painlessmesh/mesh.hpp

@@ -7,19 +7,21 @@
 #include <map>
 #include <set>
 #include <queue>
+#include <type_traits>
 
 #include "painlessmesh/configuration.hpp"
 
+#include "painlessmesh/ack.hpp"
 #include "painlessmesh/connection.hpp"
 #include "painlessmesh/gateway.hpp"
 #include "painlessmesh/logger.hpp"
 #include "painlessmesh/message_queue.hpp"
-#include "painlessmesh/message_tracker.hpp"
 #include "painlessmesh/ntp.hpp"
 #include "painlessmesh/plugin.hpp"
 #include "painlessmesh/protocol.hpp"
 #include "painlessmesh/rtc.hpp"
 #include "painlessmesh/tcp.hpp"
+#include "painlessmesh/validation.hpp"
 
 #ifdef PAINLESSMESH_ENABLE_OTA
 #include "painlessmesh/ota.hpp"
@@ -37,6 +39,38 @@ typedef std::function<void(uint32_t timestamp)> rtcSyncCompleteCallback_t;
 typedef std::function<void(bool available)> localInternetChangedCallback_t;
 typedef std::function<void(uint32_t oldPrimary, uint32_t newPrimary)> gatewayChangedCallback_t;
 
+/**
+ * Options for sendSingle() / sendBroadcast() (issue #384)
+ *
+ * Bundles the outbound queue priority and the optional delivery confirmation
+ * into one composable struct, so a message can be both prioritized and
+ * acknowledgment-tracked in a single call — something the separate priority
+ * and ack overloads cannot express:
+ *
+ * \code
+ * painlessmesh::SendOptions options;
+ * options.priority = painlessmesh::protocol::PRIORITY_HIGH;
+ * options.ackCallback = [](uint32_t nodeId, bool delivered, uint32_t ms) {};
+ * mesh.sendSingle(dest, msg, options);
+ * \endcode
+ *
+ * The priority is carried on the wire (serialized as "prio" only when it
+ * deviates from PRIORITY_NORMAL), so intermediate nodes re-enqueue a
+ * forwarded package at the sender's priority instead of dropping it to
+ * NORMAL after the first hop.
+ */
+struct SendOptions {
+  /** Outbound queue priority: PRIORITY_CRITICAL (0), PRIORITY_HIGH (1),
+   * PRIORITY_NORMAL (2, default) or PRIORITY_LOW (3). */
+  uint8_t priority = protocol::PRIORITY_NORMAL;
+  /** Optional delivery confirmation callback; fires once per expected node
+   * with delivered = true and the round-trip latency, or delivered = false
+   * on timeout. nullptr (default) disables tracking. */
+  ack::deliveryCallback_t ackCallback = nullptr;
+  /** How long to wait for acknowledgments before reporting failure. */
+  uint32_t ackTimeoutMs = 5000;
+};
+
 /**
  * Callback type for Internet request results
  *
@@ -206,10 +240,56 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
 #endif
 
     // Add package handlers
-    this->callbackList = painlessmesh::ntp::addPackageCallback(
-        std::move(this->callbackList), (*this));
-    this->callbackList = painlessmesh::router::addPackageCallback(
-        std::move(this->callbackList), (*this));
+    painlessmesh::ntp::addPackageCallback(this->callbackList, (*this));
+    painlessmesh::router::addPackageCallback(this->callbackList, (*this));
+
+    // Seed delivery-confirmation ids with a random value so they do not
+    // restart at 1 after a reboot — a delayed ACK for a pre-reboot
+    // message could otherwise match a fresh message's id and report a
+    // false delivered = true.
+    ackTracker.seed(validation::SecureRandom::generate());
+
+    // Per-message delivery confirmation (issue #379): reply with an ACK
+    // when a received application message carries a msgId. Uses the
+    // Variant field peeks — the common no-ack case must not pay for a
+    // full package materialization on every received message.
+    auto autoAck = [this](protocol::Variant& variant, std::shared_ptr<T>,
+                          uint32_t) {
+      auto msgId = variant.msgId();
+      if (msgId == 0) return false;
+      auto origin = variant.from();
+      if (origin == 0 || origin == this->nodeId) return false;
+      if (variant.type() == protocol::BROADCAST) {
+        // Stagger broadcast ACKs by nodeId so N nodes do not fire N
+        // unicast ACKs at the sender in the same instant
+        this->queueBroadcastAck(origin, msgId);
+      } else {
+        auto ackPkg = ack::MessageAckPackage(this->nodeId, origin, msgId);
+        this->sendPackage(&ackPkg);
+      }
+      return false;
+    };
+    this->callbackList.onPackage(protocol::SINGLE, autoAck);
+    this->callbackList.onPackage(protocol::BROADCAST, autoAck);
+
+    // Match incoming ACKs to messages awaiting delivery confirmation
+    this->callbackList.onPackage(
+        protocol::MESSAGE_ACK,
+        [this](protocol::Variant& variant, std::shared_ptr<T>, uint32_t) {
+          std::list<ack::DeliveryResult> results;
+          this->ackTracker.collectAck(variant.msgId(), variant.from(),
+                                      static_cast<uint32_t>(millis()),
+                                      results);
+          if (!results.empty()) {
+            this->addTask([results]() {
+              for (const auto& result : results) {
+                result.callback(result.nodeId, result.delivered,
+                                result.latencyMs);
+              }
+            });
+          }
+          return false;
+        });
 
     // Add bridge status package handler (Type BRIDGE_STATUS)
     // This will be called when any node receives a bridge status broadcast
@@ -226,6 +306,14 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
           
           if (obj["internetConnected"].is<bool>()) {
             uint32_t bridgeNodeId = obj["from"];
+            if (obj["leaving"] | false) {
+              // A bridge stepping down says so, and is forgotten at once
+              // rather than when its last status ages out — a minute and
+              // more during which every candidate held it healthy.
+              Log(GENERAL, "Bridge %u is stepping down\n", bridgeNodeId);
+              this->forgetBridge(bridgeNodeId);
+              return false;
+            }
             bool internetConnected = obj["internetConnected"];
             int8_t routerRSSI = obj["routerRSSI"] | 0;
             uint8_t routerChannel = obj["routerChannel"] | 0;
@@ -344,15 +432,36 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
       (*conn)->close();
       this->eraseClosedConnections();
     }
-    plugin::PackageHandler<T>::stop();
+    // Disable the ack task BEFORE nulling the member: if stop() was
+    // reached from inside the task's own callback, the lambda's
+    // this->ackCheckTask guard is useless once the member is null and
+    // the task would keep firing forever on an external scheduler.
+    if (ackCheckTask) ackCheckTask->disable();
+    if (broadcastAckTask) broadcastAckTask->disable();
+    ackTracker.clear();
+    pendingBroadcastAcks.clear();
+    ackCheckTask = nullptr;
+    broadcastAckTask = nullptr;
+
+    plugin::PackageHandler<T>::stop(mScheduler);
 
     newConnectionCallbacks.clear();
     droppedConnectionCallbacks.clear();
     changedConnectionCallbacks.clear();
 
     if (!isExternalScheduler) {
-      delete mScheduler;
-      mScheduler = nullptr;
+      if (mScheduler && mScheduler->getCurrentTask() != nullptr) {
+        // stop() was reached from inside a scheduler callback (e.g. a
+        // delivery/timeout callback). Deleting the scheduler here would
+        // free the object whose execute() is still on the call stack —
+        // the same bug class as issue #373. Retire it until execute()
+        // unwinds, then reclaim it during the next update.
+        retiredSchedulers.push_back(mScheduler);
+        mScheduler = nullptr;
+      } else {
+        delete mScheduler;
+        mScheduler = nullptr;
+      }
     }
   }
 
@@ -363,9 +472,16 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
    */
   void update(void) {
     if (semaphoreTake()) {
+      plugin::PackageHandler<T>::reclaimQuarantinedTasks();
+      reclaimRetiredSchedulers();
       // Check if something is executed (returns false)
       if (!mScheduler->execute())
-        Log(logger::GENERAL, "update(): Scheduler executed a task\n");
+        // DEBUG, not GENERAL: this fires every time any task runs, which on a
+        // busy node is thousands of lines a second. At GENERAL it drowned the
+        // level that carries the bridge and gateway diagnostics —
+        // sendBridgeStatus(), "Bridge status received from %u" — so nobody
+        // can turn those on to investigate a failover without being flooded.
+        Log(logger::DEBUG, "update(): Scheduler executed a task\n");
       semaphoreGive();
     }
     return;
@@ -379,12 +495,9 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
    * @return true if everything works, false if not.
    */
   bool sendSingle(uint32_t destId, TSTRING msg) {
-    Log(logger::COMMUNICATION, "sendSingle(): dest=%u msg=%s\n", destId,
-        msg.c_str());
-    auto single = painlessmesh::protocol::Single(this->nodeId, destId, msg);
-    return painlessmesh::router::send<T>(single, (*this));
+    return sendSingle(destId, msg, SendOptions());
   }
-  
+
   /** Send message to a specific node with priority
    *
    * @param destId The nodeId of the node to send it to.
@@ -394,12 +507,85 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
    * @return true if everything works, false if not.
    */
   bool sendSingle(uint32_t destId, TSTRING msg, uint8_t priorityLevel) {
-    Log(logger::COMMUNICATION, "sendSingle(): dest=%u msg=%s priority=%u\n", destId,
-        msg.c_str(), priorityLevel);
+    SendOptions options;
+    options.priority = priorityLevel;
+    return sendSingle(destId, msg, options);
+  }
+
+  /** Send message to a specific node — unified path (issue #384)
+   *
+   * All sendSingle() overloads funnel into this one. Priority and delivery
+   * confirmation compose freely; see SendOptions for the semantics of each
+   * field.
+   *
+   * @param destId The nodeId of the node to send it to.
+   * @param msg The message to send
+   * @param options Priority and/or delivery confirmation options.
+   *
+   * @return true if the message was queued for sending, false if not (no
+   *         route to destination, or — when an ackCallback is set —
+   *         PAINLESSMESH_MAX_PENDING_ACKS messages already await
+   *         acknowledgment; in both cases nothing is sent and the callback
+   *         will not fire).
+   */
+  bool sendSingle(uint32_t destId, TSTRING msg, const SendOptions& options) {
+    Log(logger::COMMUNICATION, "sendSingle(): dest=%u msg=%s priority=%u%s\n",
+        destId, msg.c_str(), options.priority,
+        options.ackCallback ? " with ack" : "");
     auto single = painlessmesh::protocol::Single(this->nodeId, destId, msg);
-    auto conn = painlessmesh::router::findRoute<T>((*this), destId);
-    if (!conn) return false;
-    return painlessmesh::router::sendWithPriority<painlessmesh::protocol::Single, T>(single, conn, priorityLevel);
+    single.priority = options.priority;
+    if (!options.ackCallback)
+      return painlessmesh::router::send<T>(single, (*this));
+    if (ackTracker.full()) {
+      Log(logger::ERROR, "sendSingle(): pending-ack limit reached\n");
+      return false;
+    }
+    single.msgId = ackTracker.nextMessageId();
+    if (!painlessmesh::router::send<T>(single, (*this))) return false;
+    ackTracker.track(single.msgId, {destId}, options.ackCallback,
+                     options.ackTimeoutMs, static_cast<uint32_t>(millis()));
+    this->ensureAckScheduling();
+    return true;
+  }
+
+  /** Send message to a specific node with delivery confirmation
+   *
+   * The message is tagged with a unique id and the destination node
+   * automatically replies with an acknowledgment. The callback fires
+   * exactly once: with delivered = true and the measured round-trip
+   * latency when the ACK arrives, or with delivered = false when
+   * ackTimeoutMs elapses without an ACK. ACK processing happens inside
+   * mesh.update() — no blocking waits.
+   *
+   * \code
+   * mesh.sendSingle(dest, msg,
+   *                 [](uint32_t nodeId, bool delivered, uint32_t latencyMs) {
+   *   if (delivered)
+   *     Serial.printf("Node %u confirmed in %u ms\n", nodeId, latencyMs);
+   *   else
+   *     Serial.printf("Delivery to %u timed out\n", nodeId);
+   * });
+   * \endcode
+   *
+   * @param destId The nodeId of the node to send it to.
+   * @param msg The message to send
+   * @param ackCallback Delivery confirmation callback. Passing nullptr
+   *        behaves exactly like the plain sendSingle().
+   * @param ackTimeoutMs How long to wait for the acknowledgment (default
+   *        5000 ms).
+   *
+   * @return true if the message was queued for sending, false if not (no
+   *         route to destination, or PAINLESSMESH_MAX_PENDING_ACKS
+   *         messages already await acknowledgment — in both cases nothing
+   *         is sent and the callback will not fire).
+   */
+  bool sendSingle(uint32_t destId, TSTRING msg,
+                  ack::deliveryCallback_t ackCallback,
+                  uint32_t ackTimeoutMs = 5000) {
+    SendOptions options;
+    options.ackCallback = ackCallback;
+    options.ackTimeoutMs = ackTimeoutMs;
+    return sendSingle(destId, msg, options);
   }
 
   /** Broadcast a message to every node on the mesh network.
@@ -409,18 +595,142 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
    * @return true if everything works, false if not
    */
   bool sendBroadcast(TSTRING msg, bool includeSelf = false) {
+    return sendBroadcast(msg, SendOptions(), includeSelf);
+  }
+
+  /** Broadcast a message to every node — unified path (issue #384)
+   *
+   * All sendBroadcast() overloads funnel into this one. Priority and
+   * delivery confirmation compose freely; see SendOptions for the semantics
+   * of each field. With an ackCallback set, the set of nodes expected to
+   * acknowledge is snapshotted from the current mesh layout (excluding this
+   * node) when the broadcast is sent, and the callback fires once per
+   * expected node. ackTimeoutMs values below 1000 ms are raised to 1000 ms
+   * so the 50 ms ACK jitter window still leaves time for routed round-trip
+   * delivery.
+   *
+   * @param msg The message to broadcast
+   * @param options Priority and/or delivery confirmation options.
+   * @param includeSelf Send message to myself as well. Default is false.
+   *
+   * @return Without an ackCallback: true if the message was queued to at
+   *         least one peer. With an ackCallback: true if the message was
+   *         queued and at least one node is expected to acknowledge, false
+   *         otherwise — including when PAINLESSMESH_MAX_PENDING_ACKS
+   *         messages already await acknowledgment (nothing is sent; the
+   *         callback will not fire).
+   */
+  bool sendBroadcast(TSTRING msg, const SendOptions& options,
+                     bool includeSelf = false) {
     using namespace logger;
-    Log(COMMUNICATION, "sendBroadcast(): msg=%s\n", msg.c_str());
+    Log(COMMUNICATION, "sendBroadcast(): msg=%s priority=%u%s\n", msg.c_str(),
+        options.priority, options.ackCallback ? " with ack" : "");
     painlessmesh::protocol::Broadcast pkg(this->nodeId, 0, msg);
+    pkg.priority = options.priority;
+
+    if (!options.ackCallback) {
+      auto success = router::broadcast<protocol::Broadcast, T>(pkg, (*this), 0);
+      if (includeSelf) {
+        protocol::Variant var(pkg);
+        this->callbackList.execute(var.type(), var, NULL, 0);
+      }
+      return success > 0;
+    }
+
+    if (ackTracker.full()) {
+      Log(ERROR, "sendBroadcast(): pending-ack limit reached\n");
+      return false;
+    }
+    // Broadcast recipients intentionally jitter ACK replies across this
+    // window. A shorter deadline would deterministically time out nodes
+    // whose slot falls after it, even when delivery is immediate.
+    auto ackTimeoutMs = options.ackTimeoutMs;
+    if (ackTimeoutMs < ACK_BROADCAST_MIN_TIMEOUT_MS)
+      ackTimeoutMs = ACK_BROADCAST_MIN_TIMEOUT_MS;
+    auto expected = this->getNodeList(false);
+    pkg.msgId = ackTracker.nextMessageId();
     auto success = router::broadcast<protocol::Broadcast, T>(pkg, (*this), 0);
+    const bool trackingPeers = success > 0 && !expected.empty();
+    if (trackingPeers) {
+      ackTracker.track(pkg.msgId, expected, options.ackCallback, ackTimeoutMs,
+                       static_cast<uint32_t>(millis()));
+      this->ensureAckScheduling();
+    }
     if (includeSelf) {
       protocol::Variant var(pkg);
       this->callbackList.execute(var.type(), var, NULL, 0);
     }
-    if (success > 0) return true;
-    return false;
+    // Do not access mesh state after self-delivery: an onReceive callback
+    // may have called stop(). Local delivery still occurs without peers,
+    // while the return value continues to describe peer ACK tracking.
+    return trackingPeers;
   }
   
+  /** Broadcast a message with per-node delivery confirmation
+   *
+   * The set of nodes expected to acknowledge is snapshotted from the
+   * current mesh layout (excluding this node) when the broadcast is sent.
+   * The callback fires once per expected node: with delivered = true and
+   * the round-trip latency when that node's ACK arrives, or with
+   * delivered = false when ackTimeoutMs elapses. The local node never
+   * acknowledges itself, even with includeSelf = true.
+   *
+   * Note: includeSelf and ackCallback are deliberately non-defaulted on
+   * this overload; C++ overload resolution against the priority overload
+   * would otherwise be ambiguous or, worse, silently convert a lambda to
+   * bool.
+   *
+   * @param msg The message to broadcast
+   * @param includeSelf Send message to myself as well.
+   * @param ackCallback Delivery confirmation callback, fired once per
+   *        node. Passing nullptr behaves like the plain sendBroadcast().
+   * @param ackTimeoutMs How long to wait for acknowledgments (default
+   *        5000 ms). Values below 1000 ms are raised to 1000 ms so the
+   *        50 ms jitter window still leaves time for routed round-trip
+   *        delivery.
+   *
+   * @return true if the message was queued and at least one node is
+   *         expected to acknowledge, false otherwise — including when
+   *         PAINLESSMESH_MAX_PENDING_ACKS messages already await
+   *         acknowledgment (nothing is sent; the callback will not
+   *         fire).
+   */
+  bool sendBroadcast(TSTRING msg, bool includeSelf,
+                     ack::deliveryCallback_t ackCallback,
+                     uint32_t ackTimeoutMs = 5000) {
+    SendOptions options;
+    options.ackCallback = ackCallback;
+    options.ackTimeoutMs = ackTimeoutMs;
+    return sendBroadcast(msg, options, includeSelf);
+  }
+
+  /** Process pending delivery acknowledgments (non-blocking poll)
+   *
+   * Schedules timeout callbacks for messages whose acknowledgment window has
+   * elapsed. Callbacks run on a later scheduler pass, after the current mesh
+   * dispatch has unwound. This also happens automatically inside
+   * mesh.update(), so calling it manually is only needed in tight loops that
+   * want prompt timeout detection.
+   *
+   * @return Number of messages still awaiting acknowledgment
+   */
+  size_t checkAcks() {
+    std::list<ack::DeliveryResult> results;
+    auto pending = ackTracker.collectExpired(static_cast<uint32_t>(millis()),
+                                             results);
+    if (!results.empty()) {
+      this->addTask([results]() {
+        for (const auto& result : results) {
+          result.callback(result.nodeId, result.delivered, result.latencyMs);
+        }
+      });
+    }
+    return pending;
+  }
+
+  /** Number of messages still awaiting delivery acknowledgment */
+  size_t pendingAcks() const { return ackTracker.pending(); }
+
   /** Broadcast a message with priority to every node on the mesh network.
    *
    * @param msg The message to broadcast
@@ -429,29 +739,20 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
    *
    * @return true if everything works, false if not
    */
-  bool sendBroadcast(TSTRING msg, uint8_t priorityLevel, bool includeSelf = false) {
-    using namespace logger;
-    Log(COMMUNICATION, "sendBroadcast(): msg=%s priority=%u\n", msg.c_str(), priorityLevel);
-    painlessmesh::protocol::Broadcast pkg(this->nodeId, 0, msg);
-    
-    // Broadcast to all connections with priority
-    size_t success = 0;
-    for (auto&& conn : this->subs) {
-      if (conn->nodeId != 0) {
-        painlessmesh::protocol::Variant variant(pkg);
-        TSTRING msgStr;
-        variant.printTo(msgStr);
-        auto sent = conn->addMessageWithPriority(msgStr, priorityLevel);
-        if (sent) ++success;
-      }
-    }
-    
-    if (includeSelf) {
-      protocol::Variant var(pkg);
-      this->callbackList.execute(var.type(), var, NULL, 0);
-    }
-    if (success > 0) return true;
-    return false;
+  template <
+      typename Priority,
+      typename IncludeSelf = bool,
+      typename std::enable_if<
+          (std::is_integral<typename std::decay<Priority>::type>::value ||
+           std::is_enum<typename std::decay<Priority>::type>::value) &&
+              !std::is_same<typename std::decay<Priority>::type, bool>::value &&
+              std::is_same<typename std::decay<IncludeSelf>::type, bool>::value,
+          int>::type = 0>
+  bool sendBroadcast(TSTRING msg, Priority priorityLevel,
+                     IncludeSelf includeSelf = false) {
+    SendOptions options;
+    options.priority = static_cast<uint8_t>(priorityLevel);
+    return sendBroadcast(msg, options, includeSelf);
   }
 
   /** Sends a node a packet to measure network trip delay to that node.
@@ -483,6 +784,15 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
    *    Serial.println(msg);
    * });
    * \endcode
+   *
+   * \note **Accumulates — does not replace.** Calling onReceive() a second
+   * time does not overwrite the previous handler; both handlers are invoked
+   * for every subsequent message, in the order they were registered. This
+   * mirrors the other on...() setters on this class (onNewConnection,
+   * onDroppedConnection, onChangedConnections, onNodeTimeAdjusted,
+   * onNodeDelayReceived). There is currently no public API to unregister
+   * a handler; if you need replace-semantics, keep a single dispatcher
+   * lambda and mutate the target it dispatches to.
    */
   void onReceive(receivedCallback_t onReceive) {
     using namespace painlessmesh;
@@ -785,6 +1095,61 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
     return this->root;
   }
 
+  // ==================== Capacity (ESP8266) ====================
+
+  /** Live connections for which this node is the access point.
+   *
+   * Every one of them holds send and receive buffers on this node's heap.
+   * A leaf has none; a node the mesh routes through has as many as attach.
+   */
+  size_t apChildren() {
+    size_t n = 0;
+    for (auto&& sub : this->subs) {
+      if (sub && sub->connected() && !sub->station) ++n;
+    }
+    return n;
+  }
+
+  /** Whether this node is being asked to do more than its part can carry.
+   *
+   * The ESP8266 is specified for small meshes, or as a **leaf** in larger
+   * ones: measured as an interior node of a seven-node mesh it runs at
+   * 10–13 KB free — a working set that tracks its live connections and the
+   * traffic through them, not a leak — and a single 8 KB package or one
+   * OTA part can then fail to allocate. This is the part's limit, not a
+   * defect. It is set by capacityCheck(), which the Arduino layer runs
+   * periodically on ESP8266 and which logs an ERROR when the condition is
+   * first met and again every five minutes it persists. Configure the node
+   * as a leaf with init(..., maxconn = 0) — or 1 to allow a single child.
+   */
+  bool overCapacity() { return _overCapacity; }
+
+  /** Evaluate the capacity rule now. Returns the new state.
+   *
+   * \param freeHeap  the part's current free heap in bytes
+   * \param floor     below this, with more than one child, is over capacity
+   */
+  bool capacityCheck(uint32_t freeHeap, uint32_t floor) {
+    using namespace logger;
+    size_t children = apChildren();
+    bool over = freeHeap < floor && children > 1;
+    uint32_t now = millis();
+    if (over && (!_overCapacity ||
+                 now - _capacityWarnedAt > CAPACITY_WARN_INTERVAL_MS)) {
+      Log(ERROR,
+          "capacity: %u B free with %u AP children on ESP8266. This part is "
+          "specified as a leaf in meshes of this size; init(..., maxconn=0) "
+          "or reduce the mesh.\n",
+          freeHeap, children);
+      _capacityWarnedAt = now;
+    }
+    _overCapacity = over;
+    return over;
+  }
+
+  static constexpr uint32_t ESP8266_CAPACITY_FLOOR = 12 * 1024;
+  static constexpr uint32_t CAPACITY_WARN_INTERVAL_MS = 5 * 60 * 1000;
+
   // ==================== Gateway Status API ====================
 
   /**
@@ -954,6 +1319,22 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
    * mesh.enableBridgeCleanup();
    * \endcode
    */
+  /**
+   * Forget one bridge now: it announced that it is stepping down.
+   *
+   * Returns whether it was known.
+   */
+  bool forgetBridge(uint32_t bridgeNodeId) {
+    size_t sizeBefore = knownBridges.size();
+    knownBridges.erase(
+        std::remove_if(knownBridges.begin(), knownBridges.end(),
+                       [bridgeNodeId](const BridgeInfo& bridge) {
+                         return bridge.nodeId == bridgeNodeId;
+                       }),
+        knownBridges.end());
+    return knownBridges.size() != sizeBefore;
+  }
+
   void cleanupExpiredBridges() {
     using namespace logger;
     size_t sizeBefore = knownBridges.size();
@@ -1279,11 +1660,39 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
     Log(COMMUNICATION, "sendToInternet(): msgId=%u dest=%s priority=%u\n",
         messageId, destination.c_str(), priority);
 
-    // Check if we have local Internet access
-    // Note: Even with local Internet, we still use the gateway protocol for consistency.
-    // A future optimization could bypass the mesh for nodes with direct Internet access.
+    // A shared gateway can execute its own gateway package locally. Keep the
+    // same package handler, pending-request tracking and callback semantics,
+    // but do not require a mesh peer merely to reach this node's own uplink.
     if (hasLocalInternet()) {
-      Log(COMMUNICATION, "sendToInternet(): Local Internet available, using gateway protocol for consistency\n");
+      PendingInternetRequest request;
+      request.messageId = messageId;
+      request.timestamp = millis();
+      request.retryCount = 0;
+      request.maxRetries = internetRetryCount;
+      request.priority = priority;
+      request.timeoutMs = internetRequestTimeout;
+      request.retryDelayMs = internetRetryDelay;
+      request.gatewayNodeId = this->nodeId;
+      request.destination = destination;
+      request.payload = payload;
+      request.callback = callback;
+      pendingInternetRequests[messageId] = request;
+
+      gateway::GatewayDataPackage pkg;
+      pkg.from = this->nodeId;
+      pkg.dest = this->nodeId;
+      pkg.messageId = messageId;
+      pkg.originNode = this->nodeId;
+      pkg.timestamp = this->getNodeTime();
+      pkg.priority = priority;
+      pkg.destination = destination;
+      pkg.payload = payload;
+      pkg.contentType = "application/json";
+      pkg.retryCount = 0;
+      pkg.requiresAck = true;
+      protocol::Variant variant(&pkg);
+      this->callbackList.execute(protocol::GATEWAY_DATA, variant, nullptr, 0);
+      return messageId;
     }
 
     // Validate mesh connectivity before attempting to send
@@ -1346,6 +1755,9 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
     bool sent = false;
     auto conn = painlessmesh::router::findRoute<T>((*this), gateway->nodeId);
     if (conn) {
+      // HTTP runs on the gateway's cooperative scheduler. Preserve this
+      // requester's route until the corresponding acknowledgment can return.
+      painlessmesh::gateway::reserveGatewayBlockingBudget(*conn);
       sent = painlessmesh::router::sendWithPriority(pkg, conn, priority);
       if (!sent) {
         Log(ERROR, "sendToInternet(): sendWithPriority failed to gateway %u (send buffer full?)\n", gateway->nodeId);
@@ -1394,6 +1806,32 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
     internetRetryDelay = delayMs;
   }
 
+  /**
+   * Configure TCP connection retry behaviour
+   *
+   * Lets latency-sensitive, high-reliability or battery-powered deployments
+   * pick their own retry envelope. Values outside safe operating bounds are
+   * clamped - see painlessmesh::tcp::clampTcpRetryConfig(). Read the applied
+   * (post-clamp) values back with getTcpRetryConfig().
+   *
+   * The defaults reproduce the previous hardcoded behaviour exactly, so
+   * existing sketches that never call this see no change.
+   *
+   * @param config Retry parameters to apply
+   */
+  void setTcpRetryConfig(const painlessmesh::tcp::TcpRetryConfig &config) {
+    tcpRetryConfig = painlessmesh::tcp::clampTcpRetryConfig(config);
+  }
+
+  /**
+   * Get the active TCP retry configuration
+   *
+   * @return The configuration currently in effect, after clamping
+   */
+  painlessmesh::tcp::TcpRetryConfig getTcpRetryConfig() const {
+    return tcpRetryConfig;
+  }
+
   /**
    * Get number of pending Internet requests
    *
@@ -1688,6 +2126,7 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
     auto conn = painlessmesh::router::findRoute<T>((*this), gateway->nodeId);
     bool sent = false;
     if (conn) {
+      painlessmesh::gateway::reserveGatewayBlockingBudget(*conn);
       sent = painlessmesh::router::sendWithPriority(pkg, conn, request.priority);
     }
 
@@ -2060,16 +2499,34 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
   //
   
   /**
-   * Enable or disable message queueing for offline mode
-   * 
-   * When enabled, messages can be queued when Internet is unavailable
-   * and automatically flushed when connection is restored.
-   * 
+   * Enable or disable the manual message queue for offline mode
+   *
+   * When enabled, allocates a `MessageQueue` that your application can
+   * push into while an upstream (MQTT/HTTP/etc.) is unreachable. The
+   * mesh does NOT flush the queue automatically and does NOT observe
+   * connectivity changes — the app is responsible for detecting when
+   * to drain it via `flushMessageQueue()` + `removeQueuedMessage()`.
+   *
+   * Wire it to your own connectivity signal, for example
+   * `onLocalInternetChanged` on the bridge node or
+   * `onBridgeStatusChanged` on downstream nodes.
+   *
    * @param enabled True to enable queueing, false to disable
    * @param maxSize Maximum number of messages in queue (default 1000)
-   * 
+   *
    * \code
    * mesh.enableMessageQueue(true, 500);  // Enable with 500 message capacity
+   *
+   * mesh.onLocalInternetChanged([&mesh](bool available) {
+   *   if (available) {
+   *     auto messages = mesh.flushMessageQueue();
+   *     for (auto& msg : messages) {
+   *       if (sendToCloud(msg.payload, msg.destination)) {
+   *         mesh.removeQueuedMessage(msg.id);
+   *       }
+   *     }
+   *   }
+   * });
    * \endcode
    */
   void enableMessageQueue(bool enabled, uint32_t maxSize = 1000) {
@@ -2084,11 +2541,13 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
   }
   
   /**
-   * Queue a message with priority for later delivery
-   * 
-   * Use this to queue critical messages when Internet is unavailable.
-   * Messages are automatically delivered when connection is restored.
-   * 
+   * Queue a message with priority for later manual delivery
+   *
+   * Use this to buffer critical messages when your upstream
+   * (MQTT/HTTP/etc.) is unavailable. The library does NOT deliver these
+   * on its own — your app must call `flushMessageQueue()` and
+   * `removeQueuedMessage()` once its own connectivity check clears.
+   *
    * @param payload Message content to queue
    * @param destination Optional destination metadata (e.g., MQTT topic, HTTP endpoint)
    * @param priority Message priority (default: PRIORITY_NORMAL)
@@ -2115,16 +2574,14 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
   }
   
   /**
-   * Flush all queued messages
-   * 
-   * Attempts to send all queued messages. This is typically called
-   * automatically when Internet connection is restored, but can be
-   * called manually.
-   * 
-   * Note: This returns the messages for the application to send.
-   * The application is responsible for actually transmitting them
-   * and calling removeQueuedMessage() when successful.
-   * 
+   * Return a snapshot of all queued messages for manual delivery
+   *
+   * This does NOT transmit anything and does NOT clear the queue. The
+   * application is responsible for actually sending each message and
+   * calling `removeQueuedMessage(id)` for each one that succeeded.
+   * Messages left in the queue remain available for retry on the next
+   * flush.
+   *
    * @return Vector of queued messages to send
    * 
    * \code
@@ -3085,11 +3542,99 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
 
   ~Mesh() {
     this->stop();
+    plugin::PackageHandler<T>::reclaimQuarantinedTasks();
+    reclaimRetiredSchedulers();
     if (!isExternalScheduler) delete mScheduler;
     if (messageQueue) delete messageQueue;
   }
 
  protected:
+  void reclaimRetiredSchedulers() {
+    for (auto it = retiredSchedulers.begin();
+         it != retiredSchedulers.end();) {
+      if ((*it)->getCurrentTask() != nullptr) {
+        ++it;
+        continue;
+      }
+      delete *it;
+      it = retiredSchedulers.erase(it);
+    }
+  }
+
+  std::list<Scheduler*> retiredSchedulers = {};
+
+  void queueBroadcastAck(uint32_t origin, uint32_t msgId) {
+    const auto key = std::make_pair(origin, msgId);
+    if (std::find(pendingBroadcastAcks.begin(), pendingBroadcastAcks.end(),
+                  key) != pendingBroadcastAcks.end())
+      return;
+    if (pendingBroadcastAcks.size() >= MAX_QUEUED_BROADCAST_ACKS) {
+      Log(logger::ERROR, "Mesh: broadcast-ack queue limit (%u) reached\n",
+          (unsigned)MAX_QUEUED_BROADCAST_ACKS);
+      return;
+    }
+    pendingBroadcastAcks.push_back(key);
+    if (!broadcastAckTask) {
+      broadcastAckTask = this->addTask(
+          [this]() {
+            while (!this->pendingBroadcastAcks.empty()) {
+              auto queued = std::move(this->pendingBroadcastAcks);
+              this->pendingBroadcastAcks.clear();
+              for (const auto& item : queued) {
+                auto pkg = ack::MessageAckPackage(this->nodeId, item.first,
+                                                  item.second);
+                this->sendPackage(&pkg);
+              }
+            }
+          },
+          this->nodeId % ACK_BROADCAST_JITTER_MS);
+    } else if (!broadcastAckTask->isEnabled() ||
+               broadcastAckTask->isLastIteration()) {
+      broadcastAckTask->restartDelayed();
+    }
+  }
+
+  /**
+   * Make sure the periodic ack-timeout task is running
+   *
+   * The task disables itself as soon as no acknowledgments are pending,
+   * so there is zero scheduler overhead when the ack API is not in use.
+   */
+  void ensureAckScheduling() {
+    if (!ackCheckTask) {
+      ackCheckTask = this->addTask(ACK_CHECK_INTERVAL_MS, TASK_FOREVER,
+                                   [this]() {
+                                     if (this->checkAcks() == 0 &&
+                                         this->ackCheckTask)
+                                       this->ackCheckTask->disable();
+                                   });
+    } else if (!ackCheckTask->isEnabled()) {
+      ackCheckTask->enable();
+    }
+  }
+
+  // Poll interval for ack timeouts while acks are pending. Note for
+  // battery/light-sleep nodes: while any ack is outstanding the
+  // scheduler wakes at this cadence for up to ackTimeoutMs; override at
+  // build time (coarser is cheaper, timeout resolution degrades
+  // accordingly).
+#ifndef PAINLESSMESH_ACK_CHECK_INTERVAL_MS
+#define PAINLESSMESH_ACK_CHECK_INTERVAL_MS 100
+#endif
+  static constexpr unsigned long ACK_CHECK_INTERVAL_MS =
+      PAINLESSMESH_ACK_CHECK_INTERVAL_MS;
+  // Broadcast ACK replies are staggered by nodeId within this window so
+  // N nodes do not converge N simultaneous unicasts on the sender
+  static constexpr uint32_t ACK_BROADCAST_JITTER_MS = 50;
+  // Allow the jittered ACK to traverse a multi-hop route after its slot.
+  static constexpr uint32_t ACK_BROADCAST_MIN_TIMEOUT_MS = 1000;
+  static constexpr size_t MAX_QUEUED_BROADCAST_ACKS =
+      PAINLESSMESH_MAX_QUEUED_BROADCAST_ACKS;
+  ack::AckTracker ackTracker;
+  std::shared_ptr<Task> ackCheckTask;
+  std::vector<std::pair<uint32_t, uint32_t> > pendingBroadcastAcks;
+  std::shared_ptr<Task> broadcastAckTask;
+
   void setScheduler(Scheduler *baseScheduler) {
     this->mScheduler = baseScheduler;
     isExternalScheduler = true;
@@ -3231,6 +3776,9 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
   uint32_t bridgeStatusIntervalMs = 30000;  // Default 30 seconds
   uint32_t bridgeTimeoutMs = 60000;         // Default 60 seconds
   bool bridgeStatusBroadcastEnabled = true;
+  // See capacityCheck(). Only ever set on ESP8266.
+  bool _overCapacity = false;
+  uint32_t _capacityWarnedAt = 0;
   
   // Bridge cleanup configuration
   static const size_t MAX_KNOWN_BRIDGES = 20;  // Memory efficient limit for ESP8266
@@ -3262,6 +3810,13 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
   uint32_t internetRetryDelay = 1000;        // Default 1 second base delay
   bool sendToInternetEnabled = false;
 
+  // TCP connect retry parameters, see setTcpRetryConfig().
+  // Public because tcp::connect<Connection, wifi::Mesh> reads it but is NOT a
+  // friend: the friend declaration below names connect<T, Mesh<T>>, whereas
+  // wifi::Mesh::tcpConnect() instantiates connect<Connection, wifi::Mesh> - a
+  // different specialisation. Same reason as the public: sections above.
+  painlessmesh::tcp::TcpRetryConfig tcpRetryConfig;
+
   friend T;
   friend void onDataCb(void *, AsyncClient *, void *, size_t);
   friend void tcpSentCb(void *, AsyncClient *, size_t, uint32_t);