From fb213208261ea2c90093881fa00e920980def8f8 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Thu, 30 Jul 2026 14:48:17 -1000
Subject: [PATCH] [api] Fix double free when overflow buffer drain is
 re-entered (#17969)

---
 .../components/api/api_overflow_buffer.cpp    | 21 +++++++++++++++++--
 esphome/components/api/api_overflow_buffer.h  |  4 ++++
 2 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/esphome/components/api/api_overflow_buffer.cpp b/esphome/components/api/api_overflow_buffer.cpp
index e242d4553e4..a57a2fb1bba 100644
--- a/esphome/components/api/api_overflow_buffer.cpp
+++ b/esphome/components/api/api_overflow_buffer.cpp
@@ -12,6 +12,22 @@ APIOverflowBuffer::~APIOverflowBuffer() {
 }
 
 ssize_t APIOverflowBuffer::try_drain(socket::Socket *socket) {
+  // socket->write() can re-enter this function: a log message emitted from an
+  // lwip callback during the write goes out over the API and lands back in the
+  // frame helper's write/drain path. If a nested drain ran here it would send
+  // and free the entry the outer drain is still holding, causing a double free.
+  // Report "no progress" instead; the outer drain keeps draining, and the
+  // nested send is enqueued behind the existing backlog.
+  if (this->draining_)
+    return 0;
+
+  // RAII so the flag is cleared on every return path
+  struct DrainGuard {
+    explicit DrainGuard(bool &flag) : flag_(flag) { flag_ = true; }
+    ~DrainGuard() { this->flag_ = false; }
+    bool &flag_;
+  } guard(this->draining_);
+
   while (this->count_ > 0) {
     Entry *front = this->queue_[this->head_];
 
@@ -29,11 +45,12 @@ ssize_t APIOverflowBuffer::try_drain(socket::Socket *socket) {
       return sent;
     }
 
-    // Entry fully sent — free it and advance
-    Entry::destroy(front);
+    // Entry fully sent — unlink it before freeing so a freed pointer is never
+    // reachable from the queue
     this->queue_[this->head_] = nullptr;
     this->head_ = (this->head_ + 1) % API_MAX_SEND_QUEUE;
     this->count_--;
+    Entry::destroy(front);
   }
 
   return 0;  // All drained
diff --git a/esphome/components/api/api_overflow_buffer.h b/esphome/components/api/api_overflow_buffer.h
index 19aae680f01..1227e831261 100644
--- a/esphome/components/api/api_overflow_buffer.h
+++ b/esphome/components/api/api_overflow_buffer.h
@@ -69,6 +69,10 @@ class APIOverflowBuffer {
   uint8_t head_{0};
   uint8_t tail_{0};
   uint8_t count_{0};
+  // Guards against re-entrant drains: socket->write() can re-enter the API
+  // send path (e.g. a log message emitted from an lwip callback), and a nested
+  // drain would free the entry the outer drain is still holding.
+  bool draining_{false};
 };
 
 }  // namespace esphome::api