From c970c38e8b6a6c8942b6864b5a48d2f1bd156acd Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@home-assistant.io>
Date: Sun, 29 Mar 2026 11:49:52 -1000
Subject: [PATCH] [api] Replace check_data_state_ with debug assert in write
 methods
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Callers already guarantee DATA state before calling write_protobuf_packet
(via try_to_clear_buffer) and write_protobuf_messages (via loop processing).
The runtime check is unreachable — replaced with ESPHOME_DEBUG_API assert.
---
 esphome/components/api/api_frame_helper.h             |  5 +++--
 esphome/components/api/api_frame_helper_noise.cpp     | 10 ++++------
 esphome/components/api/api_frame_helper_plaintext.cpp | 10 ++++------
 3 files changed, 11 insertions(+), 14 deletions(-)

diff --git a/esphome/components/api/api_frame_helper.h b/esphome/components/api/api_frame_helper.h
index a5823077385..768cffdebbd 100644
--- a/esphome/components/api/api_frame_helper.h
+++ b/esphome/components/api/api_frame_helper.h
@@ -161,10 +161,11 @@ class APIFrameHelper {
       this->nodelay_counter_ = 0;
     }
   }
-  // Write a single protobuf message - the hot path (87-100% of all writes)
+  // Write a single protobuf message - the hot path (87-100% of all writes).
+  // Caller must ensure state is DATA before calling.
   virtual APIError write_protobuf_packet(uint8_t type, ProtoWriteBuffer buffer) = 0;
   // Write multiple protobuf messages in a single batched operation.
-  // messages must not be empty — caller is responsible for checking.
+  // Caller must ensure state is DATA and messages is not empty.
   // messages contains (message_type, offset, length) for each message in the buffer.
   // The buffer contains all messages with appropriate padding before each.
   virtual APIError write_protobuf_messages(ProtoWriteBuffer buffer, std::span<const MessageInfo> messages) = 0;
diff --git a/esphome/components/api/api_frame_helper_noise.cpp b/esphome/components/api/api_frame_helper_noise.cpp
index d6b4a72cae6..94f4780fb1a 100644
--- a/esphome/components/api/api_frame_helper_noise.cpp
+++ b/esphome/components/api/api_frame_helper_noise.cpp
@@ -489,9 +489,9 @@ APIError APINoiseFrameHelper::encrypt_noise_message_(uint8_t *buf_start, const M
 }
 
 APIError APINoiseFrameHelper::write_protobuf_packet(uint8_t type, ProtoWriteBuffer buffer) {
-  APIError aerr = this->check_data_state_();
-  if (aerr != APIError::OK)
-    return aerr;
+#ifdef ESPHOME_DEBUG_API
+  assert(this->state_ == State::DATA);
+#endif
 
   // Resize buffer to include footer space for Noise MAC
   if (frame_footer_size_)
@@ -508,10 +508,8 @@ APIError APINoiseFrameHelper::write_protobuf_packet(uint8_t type, ProtoWriteBuff
 }
 
 APIError APINoiseFrameHelper::write_protobuf_messages(ProtoWriteBuffer buffer, std::span<const MessageInfo> messages) {
-  APIError aerr = this->check_data_state_();
-  if (aerr != APIError::OK)
-    return aerr;
 #ifdef ESPHOME_DEBUG_API
+  assert(this->state_ == State::DATA);
   assert(!messages.empty());
 #endif
 
diff --git a/esphome/components/api/api_frame_helper_plaintext.cpp b/esphome/components/api/api_frame_helper_plaintext.cpp
index a21d177b7f7..9144a0234bd 100644
--- a/esphome/components/api/api_frame_helper_plaintext.cpp
+++ b/esphome/components/api/api_frame_helper_plaintext.cpp
@@ -285,9 +285,9 @@ ESPHOME_ALWAYS_INLINE static inline uint8_t *write_plaintext_header(uint8_t *buf
 }
 
 APIError APIPlaintextFrameHelper::write_protobuf_packet(uint8_t type, ProtoWriteBuffer buffer) {
-  APIError aerr = this->check_data_state_();
-  if (aerr != APIError::OK)
-    return aerr;
+#ifdef ESPHOME_DEBUG_API
+  assert(this->state_ == State::DATA);
+#endif
 
   MessageInfo msg{type, 0, static_cast<uint16_t>(buffer.get_buffer()->size() - frame_header_padding_)};
   uint8_t *buffer_data = buffer.get_buffer()->data();
@@ -299,10 +299,8 @@ APIError APIPlaintextFrameHelper::write_protobuf_packet(uint8_t type, ProtoWrite
 
 APIError APIPlaintextFrameHelper::write_protobuf_messages(ProtoWriteBuffer buffer,
                                                           std::span<const MessageInfo> messages) {
-  APIError aerr = this->check_data_state_();
-  if (aerr != APIError::OK)
-    return aerr;
 #ifdef ESPHOME_DEBUG_API
+  assert(this->state_ == State::DATA);
   assert(!messages.empty());
 #endif