esphome 2025.4.2__py3-none-any.whl → 2025.5.0b3__py3-none-any.whl

esphome/components/api/api_frame_helper.cpp

@@ -5,6 +5,7 @@
 #include "esphome/core/helpers.h"
 #include "esphome/core/application.h"
 #include "proto.h"
+#include "api_pb2_size.h"
 #include <cstring>
 
 namespace esphome {
@@ -72,6 +73,91 @@ const char *api_error_to_str(APIError err) {
   return "UNKNOWN";
 }
 
+// Common implementation for writing raw data to socket
+template<typename StateEnum>
+APIError APIFrameHelper::write_raw_(const struct iovec *iov, int iovcnt, socket::Socket *socket,
+                                    std::vector<uint8_t> &tx_buf, const std::string &info, StateEnum &state,
+                                    StateEnum failed_state) {
+  // This method writes data to socket or buffers it
+  // Returns APIError::OK if successful (or would block, but data has been buffered)
+  // Returns APIError::SOCKET_WRITE_FAILED if socket write failed, and sets state to failed_state
+
+  if (iovcnt == 0)
+    return APIError::OK;  // Nothing to do, success
+
+  size_t total_write_len = 0;
+  for (int i = 0; i < iovcnt; i++) {
+#ifdef HELPER_LOG_PACKETS
+    ESP_LOGVV(TAG, "Sending raw: %s",
+              format_hex_pretty(reinterpret_cast<uint8_t *>(iov[i].iov_base), iov[i].iov_len).c_str());
+#endif
+    total_write_len += iov[i].iov_len;
+  }
+
+  if (!tx_buf.empty()) {
+    // try to empty tx_buf first
+    while (!tx_buf.empty()) {
+      ssize_t sent = socket->write(tx_buf.data(), tx_buf.size());
+      if (is_would_block(sent)) {
+        break;
+      } else if (sent == -1) {
+        ESP_LOGVV(TAG, "%s: Socket write failed with errno %d", info.c_str(), errno);
+        state = failed_state;
+        return APIError::SOCKET_WRITE_FAILED;  // Socket write failed
+      }
+      // TODO: inefficient if multiple packets in txbuf
+      // replace with deque of buffers
+      tx_buf.erase(tx_buf.begin(), tx_buf.begin() + sent);
+    }
+  }
+
+  if (!tx_buf.empty()) {
+    // tx buf not empty, can't write now because then stream would be inconsistent
+    // Reserve space upfront to avoid multiple reallocations
+    tx_buf.reserve(tx_buf.size() + total_write_len);
+    for (int i = 0; i < iovcnt; i++) {
+      tx_buf.insert(tx_buf.end(), reinterpret_cast<uint8_t *>(iov[i].iov_base),
+                    reinterpret_cast<uint8_t *>(iov[i].iov_base) + iov[i].iov_len);
+    }
+    return APIError::OK;  // Success, data buffered
+  }
+
+  ssize_t sent = socket->writev(iov, iovcnt);
+  if (is_would_block(sent)) {
+    // operation would block, add buffer to tx_buf
+    // Reserve space upfront to avoid multiple reallocations
+    tx_buf.reserve(tx_buf.size() + total_write_len);
+    for (int i = 0; i < iovcnt; i++) {
+      tx_buf.insert(tx_buf.end(), reinterpret_cast<uint8_t *>(iov[i].iov_base),
+                    reinterpret_cast<uint8_t *>(iov[i].iov_base) + iov[i].iov_len);
+    }
+    return APIError::OK;  // Success, data buffered
+  } else if (sent == -1) {
+    // an error occurred
+    ESP_LOGVV(TAG, "%s: Socket write failed with errno %d", info.c_str(), errno);
+    state = failed_state;
+    return APIError::SOCKET_WRITE_FAILED;  // Socket write failed
+  } else if ((size_t) sent != total_write_len) {
+    // partially sent, add end to tx_buf
+    size_t remaining = total_write_len - sent;
+    // Reserve space upfront to avoid multiple reallocations
+    tx_buf.reserve(tx_buf.size() + remaining);
+
+    size_t to_consume = sent;
+    for (int i = 0; i < iovcnt; i++) {
+      if (to_consume >= iov[i].iov_len) {
+        to_consume -= iov[i].iov_len;
+      } else {
+        tx_buf.insert(tx_buf.end(), reinterpret_cast<uint8_t *>(iov[i].iov_base) + to_consume,
+                      reinterpret_cast<uint8_t *>(iov[i].iov_base) + iov[i].iov_len);
+        to_consume = 0;
+      }
+    }
+    return APIError::OK;  // Success, data buffered
+  }
+  return APIError::OK;  // Success, all data sent
+}
+
 #define HELPER_LOG(msg, ...) ESP_LOGVV(TAG, "%s: " msg, info_.c_str(), ##__VA_ARGS__)
 // uncomment to log raw packets
 //#define HELPER_LOG_PACKETS
@@ -407,9 +493,12 @@ void APINoiseFrameHelper::send_explicit_handshake_reject_(const std::string &rea
   std::vector<uint8_t> data;
   data.resize(reason.length() + 1);
   data[0] = 0x01;  // failure
-  for (size_t i = 0; i < reason.length(); i++) {
-    data[i + 1] = (uint8_t) reason[i];
+
+  // Copy error message in bulk
+  if (!reason.empty()) {
+    std::memcpy(data.data() + 1, reason.c_str(), reason.length());
   }
+
   // temporarily remove failed state
   auto orig_state = state_;
   state_ = State::EXPLICIT_REJECT;
@@ -471,7 +560,7 @@ APIError APINoiseFrameHelper::read_packet(ReadPacketBuffer *buffer) {
   return APIError::OK;
 }
 bool APINoiseFrameHelper::can_write_without_blocking() { return state_ == State::DATA && tx_buf_.empty(); }
-APIError APINoiseFrameHelper::write_packet(uint16_t type, const uint8_t *payload, size_t payload_len) {
+APIError APINoiseFrameHelper::write_protobuf_packet(uint16_t type, ProtoWriteBuffer buffer) {
   int err;
   APIError aerr;
   aerr = state_action_();
@@ -483,31 +572,36 @@ APIError APINoiseFrameHelper::write_packet(uint16_t type, const uint8_t *payload
     return APIError::WOULD_BLOCK;
   }
 
+  std::vector<uint8_t> *raw_buffer = buffer.get_buffer();
+  // Message data starts after padding
+  size_t payload_len = raw_buffer->size() - frame_header_padding_;
   size_t padding = 0;
   size_t msg_len = 4 + payload_len + padding;
-  size_t frame_len = 3 + msg_len + noise_cipherstate_get_mac_length(send_cipher_);
-  auto tmpbuf = std::unique_ptr<uint8_t[]>{new (std::nothrow) uint8_t[frame_len]};
-  if (tmpbuf == nullptr) {
-    HELPER_LOG("Could not allocate for writing packet");
-    return APIError::OUT_OF_MEMORY;
-  }
 
-  tmpbuf[0] = 0x01;  // indicator
-  // tmpbuf[1], tmpbuf[2] to be set later
+  // We need to resize to include MAC space, but we already reserved it in create_buffer
+  raw_buffer->resize(raw_buffer->size() + frame_footer_size_);
+
+  // Write the noise header in the padded area
+  // Buffer layout:
+  // [0]    - 0x01 indicator byte
+  // [1-2]  - Size of encrypted payload (filled after encryption)
+  // [3-4]  - Message type (encrypted)
+  // [5-6]  - Payload length (encrypted)
+  // [7...] - Actual payload data (encrypted)
+  uint8_t *buf_start = raw_buffer->data();
+  buf_start[0] = 0x01;  // indicator
+  // buf_start[1], buf_start[2] to be set later after encryption
   const uint8_t msg_offset = 3;
-  const uint8_t payload_offset = msg_offset + 4;
-  tmpbuf[msg_offset + 0] = (uint8_t) (type >> 8);  // type
-  tmpbuf[msg_offset + 1] = (uint8_t) type;
-  tmpbuf[msg_offset + 2] = (uint8_t) (payload_len >> 8);  // data_len
-  tmpbuf[msg_offset + 3] = (uint8_t) payload_len;
-  // copy data
-  std::copy(payload, payload + payload_len, &tmpbuf[payload_offset]);
-  // fill padding with zeros
-  std::fill(&tmpbuf[payload_offset + payload_len], &tmpbuf[frame_len], 0);
+  buf_start[msg_offset + 0] = (uint8_t) (type >> 8);         // type high byte
+  buf_start[msg_offset + 1] = (uint8_t) type;                // type low byte
+  buf_start[msg_offset + 2] = (uint8_t) (payload_len >> 8);  // data_len high byte
+  buf_start[msg_offset + 3] = (uint8_t) payload_len;         // data_len low byte
+  // payload data is already in the buffer starting at position 7
 
   NoiseBuffer mbuf;
   noise_buffer_init(mbuf);
-  noise_buffer_set_inout(mbuf, &tmpbuf[msg_offset], msg_len, frame_len - msg_offset);
+  // The capacity parameter should be msg_len + frame_footer_size_ (MAC length) to allow space for encryption
+  noise_buffer_set_inout(mbuf, buf_start + msg_offset, msg_len, msg_len + frame_footer_size_);
   err = noise_cipherstate_encrypt(send_cipher_, &mbuf);
   if (err != 0) {
     state_ = State::FAILED;
@@ -516,11 +610,13 @@ APIError APINoiseFrameHelper::write_packet(uint16_t type, const uint8_t *payload
   }
 
   size_t total_len = 3 + mbuf.size;
-  tmpbuf[1] = (uint8_t) (mbuf.size >> 8);
-  tmpbuf[2] = (uint8_t) mbuf.size;
+  buf_start[1] = (uint8_t) (mbuf.size >> 8);
+  buf_start[2] = (uint8_t) mbuf.size;
 
   struct iovec iov;
-  iov.iov_base = &tmpbuf[0];
+  // Point iov_base to the beginning of the buffer (no unused padding in Noise)
+  // We send the entire frame: indicator + size + encrypted(type + data_len + payload + MAC)
+  iov.iov_base = buf_start;
   iov.iov_len = total_len;
 
   // write raw to not have two packets sent if NAGLE disabled
@@ -546,71 +642,6 @@ APIError APINoiseFrameHelper::try_send_tx_buf_() {
 
   return APIError::OK;
 }
-/** Write the data to the socket, or buffer it a write would block
- *
- * @param data The data to write
- * @param len The length of data
- */
-APIError APINoiseFrameHelper::write_raw_(const struct iovec *iov, int iovcnt) {
-  if (iovcnt == 0)
-    return APIError::OK;
-  APIError aerr;
-
-  size_t total_write_len = 0;
-  for (int i = 0; i < iovcnt; i++) {
-#ifdef HELPER_LOG_PACKETS
-    ESP_LOGVV(TAG, "Sending raw: %s",
-              format_hex_pretty(reinterpret_cast<uint8_t *>(iov[i].iov_base), iov[i].iov_len).c_str());
-#endif
-    total_write_len += iov[i].iov_len;
-  }
-
-  if (!tx_buf_.empty()) {
-    // try to empty tx_buf_ first
-    aerr = try_send_tx_buf_();
-    if (aerr != APIError::OK && aerr != APIError::WOULD_BLOCK)
-      return aerr;
-  }
-
-  if (!tx_buf_.empty()) {
-    // tx buf not empty, can't write now because then stream would be inconsistent
-    for (int i = 0; i < iovcnt; i++) {
-      tx_buf_.insert(tx_buf_.end(), reinterpret_cast<uint8_t *>(iov[i].iov_base),
-                     reinterpret_cast<uint8_t *>(iov[i].iov_base) + iov[i].iov_len);
-    }
-    return APIError::OK;
-  }
-
-  ssize_t sent = socket_->writev(iov, iovcnt);
-  if (is_would_block(sent)) {
-    // operation would block, add buffer to tx_buf
-    for (int i = 0; i < iovcnt; i++) {
-      tx_buf_.insert(tx_buf_.end(), reinterpret_cast<uint8_t *>(iov[i].iov_base),
-                     reinterpret_cast<uint8_t *>(iov[i].iov_base) + iov[i].iov_len);
-    }
-    return APIError::OK;
-  } else if (sent == -1) {
-    // an error occurred
-    state_ = State::FAILED;
-    HELPER_LOG("Socket write failed with errno %d", errno);
-    return APIError::SOCKET_WRITE_FAILED;
-  } else if ((size_t) sent != total_write_len) {
-    // partially sent, add end to tx_buf
-    size_t to_consume = sent;
-    for (int i = 0; i < iovcnt; i++) {
-      if (to_consume >= iov[i].iov_len) {
-        to_consume -= iov[i].iov_len;
-      } else {
-        tx_buf_.insert(tx_buf_.end(), reinterpret_cast<uint8_t *>(iov[i].iov_base) + to_consume,
-                       reinterpret_cast<uint8_t *>(iov[i].iov_base) + iov[i].iov_len);
-        to_consume = 0;
-      }
-    }
-    return APIError::OK;
-  }
-  // fully sent
-  return APIError::OK;
-}
 APIError APINoiseFrameHelper::write_frame_(const uint8_t *data, size_t len) {
   uint8_t header[3];
   header[0] = 0x01;  // indicator
@@ -697,6 +728,8 @@ APIError APINoiseFrameHelper::check_handshake_finished_() {
     return APIError::HANDSHAKESTATE_SPLIT_FAILED;
   }
 
+  frame_footer_size_ = noise_cipherstate_get_mac_length(send_cipher_);
+
   HELPER_LOG("Handshake complete!");
   noise_handshakestate_free(handshake_);
   handshake_ = nullptr;
@@ -744,6 +777,11 @@ void noise_rand_bytes(void *output, size_t len) {
   }
 }
 }
+
+// Explicit template instantiation for Noise
+template APIError APIFrameHelper::write_raw_<APINoiseFrameHelper::State>(
+    const struct iovec *iov, int iovcnt, socket::Socket *socket, std::vector<uint8_t> &tx_buf_, const std::string &info,
+    APINoiseFrameHelper::State &state, APINoiseFrameHelper::State failed_state);
 #endif  // USE_API_NOISE
 
 #ifdef USE_API_PLAINTEXT
@@ -804,6 +842,10 @@ APIError APIPlaintextFrameHelper::try_read_frame_(ParsedFrame *frame) {
   // read header
   while (!rx_header_parsed_) {
     uint8_t data;
+    // Reading one byte at a time is fastest in practice for ESP32 when
+    // there is no data on the wire (which is the common case).
+    // This results in faster failure detection compared to
+    // attempting to read multiple bytes at once.
     ssize_t received = socket_->read(&data, 1);
     if (received == -1) {
       if (errno == EWOULDBLOCK || errno == EAGAIN) {
@@ -817,27 +859,60 @@ APIError APIPlaintextFrameHelper::try_read_frame_(ParsedFrame *frame) {
       HELPER_LOG("Connection closed");
       return APIError::CONNECTION_CLOSED;
     }
-    rx_header_buf_.push_back(data);
 
-    // try parse header
-    if (rx_header_buf_[0] != 0x00) {
+    // Successfully read a byte
+
+    // Process byte according to current buffer position
+    if (rx_header_buf_pos_ == 0) {  // Case 1: First byte (indicator byte)
+      if (data != 0x00) {
+        state_ = State::FAILED;
+        HELPER_LOG("Bad indicator byte %u", data);
+        return APIError::BAD_INDICATOR;
+      }
+      // We don't store the indicator byte, just increment position
+      rx_header_buf_pos_ = 1;  // Set to 1 directly
+      continue;                // Need more bytes before we can parse
+    }
+
+    // Check buffer overflow before storing
+    if (rx_header_buf_pos_ == 5) {  // Case 2: Buffer would overflow (5 bytes is max allowed)
       state_ = State::FAILED;
-      HELPER_LOG("Bad indicator byte %u", rx_header_buf_[0]);
-      return APIError::BAD_INDICATOR;
+      HELPER_LOG("Header buffer overflow");
+      return APIError::BAD_DATA_PACKET;
     }
 
-    size_t i = 1;
+    // Store byte in buffer (adjust index to account for skipped indicator byte)
+    rx_header_buf_[rx_header_buf_pos_ - 1] = data;
+
+    // Increment position after storing
+    rx_header_buf_pos_++;
+
+    // Case 3: If we only have one varint byte, we need more
+    if (rx_header_buf_pos_ == 2) {  // Have read indicator + 1 byte
+      continue;                     // Need more bytes before we can parse
+    }
+
+    // At this point, we have at least 3 bytes total:
+    //   - Validated indicator byte (0x00) but not stored
+    //   - At least 2 bytes in the buffer for the varints
+    // Buffer layout:
+    //   First 1-3 bytes: Message size varint (variable length)
+    //     - 2 bytes would only allow up to 16383, which is less than noise's 65535
+    //     - 3 bytes allows up to 2097151, ensuring we support at least as much as noise
+    //   Remaining 1-2 bytes: Message type varint (variable length)
+    // We now attempt to parse both varints. If either is incomplete,
+    // we'll continue reading more bytes.
+
     uint32_t consumed = 0;
-    auto msg_size_varint = ProtoVarInt::parse(&rx_header_buf_[i], rx_header_buf_.size() - i, &consumed);
+    auto msg_size_varint = ProtoVarInt::parse(&rx_header_buf_[0], rx_header_buf_pos_ - 1, &consumed);
     if (!msg_size_varint.has_value()) {
       // not enough data there yet
       continue;
     }
 
-    i += consumed;
     rx_header_parsed_len_ = msg_size_varint->as_uint32();
 
-    auto msg_type_varint = ProtoVarInt::parse(&rx_header_buf_[i], rx_header_buf_.size() - i, &consumed);
+    auto msg_type_varint = ProtoVarInt::parse(&rx_header_buf_[consumed], rx_header_buf_pos_ - 1 - consumed, &consumed);
     if (!msg_type_varint.has_value()) {
       // not enough data there yet
       continue;
@@ -883,7 +958,7 @@ APIError APIPlaintextFrameHelper::try_read_frame_(ParsedFrame *frame) {
   // consume msg
   rx_buf_ = {};
   rx_buf_len_ = 0;
-  rx_header_buf_.clear();
+  rx_header_buf_pos_ = 0;
   rx_header_parsed_ = false;
   return APIError::OK;
 }
@@ -927,26 +1002,66 @@ APIError APIPlaintextFrameHelper::read_packet(ReadPacketBuffer *buffer) {
   return APIError::OK;
 }
 bool APIPlaintextFrameHelper::can_write_without_blocking() { return state_ == State::DATA && tx_buf_.empty(); }
-APIError APIPlaintextFrameHelper::write_packet(uint16_t type, const uint8_t *payload, size_t payload_len) {
+APIError APIPlaintextFrameHelper::write_protobuf_packet(uint16_t type, ProtoWriteBuffer buffer) {
   if (state_ != State::DATA) {
     return APIError::BAD_STATE;
   }
 
-  std::vector<uint8_t> header;
-  header.push_back(0x00);
-  ProtoVarInt(payload_len).encode(header);
-  ProtoVarInt(type).encode(header);
+  std::vector<uint8_t> *raw_buffer = buffer.get_buffer();
+  // Message data starts after padding (frame_header_padding_ = 6)
+  size_t payload_len = raw_buffer->size() - frame_header_padding_;
 
-  struct iovec iov[2];
-  iov[0].iov_base = &header[0];
-  iov[0].iov_len = header.size();
-  if (payload_len == 0) {
-    return write_raw_(iov, 1);
+  // Calculate varint sizes for header components
+  size_t size_varint_len = api::ProtoSize::varint(static_cast<uint32_t>(payload_len));
+  size_t type_varint_len = api::ProtoSize::varint(static_cast<uint32_t>(type));
+  size_t total_header_len = 1 + size_varint_len + type_varint_len;
+
+  if (total_header_len > frame_header_padding_) {
+    // Header is too large to fit in the padding
+    return APIError::BAD_ARG;
   }
-  iov[1].iov_base = const_cast<uint8_t *>(payload);
-  iov[1].iov_len = payload_len;
 
-  return write_raw_(iov, 2);
+  // Calculate where to start writing the header
+  // The header starts at the latest possible position to minimize unused padding
+  //
+  // Example 1 (small values): total_header_len = 3, header_offset = 6 - 3 = 3
+  // [0-2]  - Unused padding
+  // [3]    - 0x00 indicator byte
+  // [4]    - Payload size varint (1 byte, for sizes 0-127)
+  // [5]    - Message type varint (1 byte, for types 0-127)
+  // [6...] - Actual payload data
+  //
+  // Example 2 (medium values): total_header_len = 4, header_offset = 6 - 4 = 2
+  // [0-1]  - Unused padding
+  // [2]    - 0x00 indicator byte
+  // [3-4]  - Payload size varint (2 bytes, for sizes 128-16383)
+  // [5]    - Message type varint (1 byte, for types 0-127)
+  // [6...] - Actual payload data
+  //
+  // Example 3 (large values): total_header_len = 6, header_offset = 6 - 6 = 0
+  // [0]    - 0x00 indicator byte
+  // [1-3]  - Payload size varint (3 bytes, for sizes 16384-2097151)
+  // [4-5]  - Message type varint (2 bytes, for types 128-32767)
+  // [6...] - Actual payload data
+  uint8_t *buf_start = raw_buffer->data();
+  size_t header_offset = frame_header_padding_ - total_header_len;
+
+  // Write the plaintext header
+  buf_start[header_offset] = 0x00;  // indicator
+
+  // Encode size varint directly into buffer
+  ProtoVarInt(payload_len).encode_to_buffer_unchecked(buf_start + header_offset + 1, size_varint_len);
+
+  // Encode type varint directly into buffer
+  ProtoVarInt(type).encode_to_buffer_unchecked(buf_start + header_offset + 1 + size_varint_len, type_varint_len);
+
+  struct iovec iov;
+  // Point iov_base to the beginning of our header (skip unused padding)
+  // This ensures we only send the actual header and payload, not the empty padding bytes
+  iov.iov_base = buf_start + header_offset;
+  iov.iov_len = total_header_len + payload_len;
+
+  return write_raw_(&iov, 1);
 }
 APIError APIPlaintextFrameHelper::try_send_tx_buf_() {
   // try send from tx_buf
@@ -966,71 +1081,6 @@ APIError APIPlaintextFrameHelper::try_send_tx_buf_() {
 
   return APIError::OK;
 }
-/** Write the data to the socket, or buffer it a write would block
- *
- * @param data The data to write
- * @param len The length of data
- */
-APIError APIPlaintextFrameHelper::write_raw_(const struct iovec *iov, int iovcnt) {
-  if (iovcnt == 0)
-    return APIError::OK;
-  APIError aerr;
-
-  size_t total_write_len = 0;
-  for (int i = 0; i < iovcnt; i++) {
-#ifdef HELPER_LOG_PACKETS
-    ESP_LOGVV(TAG, "Sending raw: %s",
-              format_hex_pretty(reinterpret_cast<uint8_t *>(iov[i].iov_base), iov[i].iov_len).c_str());
-#endif
-    total_write_len += iov[i].iov_len;
-  }
-
-  if (!tx_buf_.empty()) {
-    // try to empty tx_buf_ first
-    aerr = try_send_tx_buf_();
-    if (aerr != APIError::OK && aerr != APIError::WOULD_BLOCK)
-      return aerr;
-  }
-
-  if (!tx_buf_.empty()) {
-    // tx buf not empty, can't write now because then stream would be inconsistent
-    for (int i = 0; i < iovcnt; i++) {
-      tx_buf_.insert(tx_buf_.end(), reinterpret_cast<uint8_t *>(iov[i].iov_base),
-                     reinterpret_cast<uint8_t *>(iov[i].iov_base) + iov[i].iov_len);
-    }
-    return APIError::OK;
-  }
-
-  ssize_t sent = socket_->writev(iov, iovcnt);
-  if (is_would_block(sent)) {
-    // operation would block, add buffer to tx_buf
-    for (int i = 0; i < iovcnt; i++) {
-      tx_buf_.insert(tx_buf_.end(), reinterpret_cast<uint8_t *>(iov[i].iov_base),
-                     reinterpret_cast<uint8_t *>(iov[i].iov_base) + iov[i].iov_len);
-    }
-    return APIError::OK;
-  } else if (sent == -1) {
-    // an error occurred
-    state_ = State::FAILED;
-    HELPER_LOG("Socket write failed with errno %d", errno);
-    return APIError::SOCKET_WRITE_FAILED;
-  } else if ((size_t) sent != total_write_len) {
-    // partially sent, add end to tx_buf
-    size_t to_consume = sent;
-    for (int i = 0; i < iovcnt; i++) {
-      if (to_consume >= iov[i].iov_len) {
-        to_consume -= iov[i].iov_len;
-      } else {
-        tx_buf_.insert(tx_buf_.end(), reinterpret_cast<uint8_t *>(iov[i].iov_base) + to_consume,
-                       reinterpret_cast<uint8_t *>(iov[i].iov_base) + iov[i].iov_len);
-        to_consume = 0;
-      }
-    }
-    return APIError::OK;
-  }
-  // fully sent
-  return APIError::OK;
-}
 
 APIError APIPlaintextFrameHelper::close() {
   state_ = State::CLOSED;
@@ -1048,6 +1098,11 @@ APIError APIPlaintextFrameHelper::shutdown(int how) {
   }
   return APIError::OK;
 }
+
+// Explicit template instantiation for Plaintext
+template APIError APIFrameHelper::write_raw_<APIPlaintextFrameHelper::State>(
+    const struct iovec *iov, int iovcnt, socket::Socket *socket, std::vector<uint8_t> &tx_buf_, const std::string &info,
+    APIPlaintextFrameHelper::State &state, APIPlaintextFrameHelper::State failed_state);
 #endif  // USE_API_PLAINTEXT
 
 }  // namespace api

esphome/components/api/api_frame_helper.h

@@ -16,6 +16,8 @@
 namespace esphome {
 namespace api {
 
+class ProtoWriteBuffer;
+
 struct ReadPacketBuffer {
   std::vector<uint8_t> container;
   uint16_t type;
@@ -65,26 +67,46 @@ class APIFrameHelper {
   virtual APIError loop() = 0;
   virtual APIError read_packet(ReadPacketBuffer *buffer) = 0;
   virtual bool can_write_without_blocking() = 0;
-  virtual APIError write_packet(uint16_t type, const uint8_t *data, size_t len) = 0;
+  virtual APIError write_protobuf_packet(uint16_t type, ProtoWriteBuffer buffer) = 0;
   virtual std::string getpeername() = 0;
   virtual int getpeername(struct sockaddr *addr, socklen_t *addrlen) = 0;
   virtual APIError close() = 0;
   virtual APIError shutdown(int how) = 0;
   // Give this helper a name for logging
   virtual void set_log_info(std::string info) = 0;
+  // Get the frame header padding required by this protocol
+  virtual uint8_t frame_header_padding() = 0;
+  // Get the frame footer size required by this protocol
+  virtual uint8_t frame_footer_size() = 0;
+
+ protected:
+  // Common implementation for writing raw data to socket
+  template<typename StateEnum>
+  APIError write_raw_(const struct iovec *iov, int iovcnt, socket::Socket *socket, std::vector<uint8_t> &tx_buf,
+                      const std::string &info, StateEnum &state, StateEnum failed_state);
+
+  uint8_t frame_header_padding_{0};
+  uint8_t frame_footer_size_{0};
 };
 
 #ifdef USE_API_NOISE
 class APINoiseFrameHelper : public APIFrameHelper {
  public:
   APINoiseFrameHelper(std::unique_ptr<socket::Socket> socket, std::shared_ptr<APINoiseContext> ctx)
-      : socket_(std::move(socket)), ctx_(std::move(std::move(ctx))) {}
+      : socket_(std::move(socket)), ctx_(std::move(ctx)) {
+    // Noise header structure:
+    // Pos 0: indicator (0x01)
+    // Pos 1-2: encrypted payload size (16-bit big-endian)
+    // Pos 3-6: encrypted type (16-bit) + data_len (16-bit)
+    // Pos 7+: actual payload data
+    frame_header_padding_ = 7;
+  }
   ~APINoiseFrameHelper() override;
   APIError init() override;
   APIError loop() override;
   APIError read_packet(ReadPacketBuffer *buffer) override;
   bool can_write_without_blocking() override;
-  APIError write_packet(uint16_t type, const uint8_t *payload, size_t len) override;
+  APIError write_protobuf_packet(uint16_t type, ProtoWriteBuffer buffer) override;
   std::string getpeername() override { return this->socket_->getpeername(); }
   int getpeername(struct sockaddr *addr, socklen_t *addrlen) override {
     return this->socket_->getpeername(addr, addrlen);
@@ -93,6 +115,10 @@ class APINoiseFrameHelper : public APIFrameHelper {
   APIError shutdown(int how) override;
   // Give this helper a name for logging
   void set_log_info(std::string info) override { info_ = std::move(info); }
+  // Get the frame header padding required by this protocol
+  uint8_t frame_header_padding() override { return frame_header_padding_; }
+  // Get the frame footer size required by this protocol
+  uint8_t frame_footer_size() override { return frame_footer_size_; }
 
  protected:
   struct ParsedFrame {
@@ -103,7 +129,9 @@ class APINoiseFrameHelper : public APIFrameHelper {
   APIError try_read_frame_(ParsedFrame *frame);
   APIError try_send_tx_buf_();
   APIError write_frame_(const uint8_t *data, size_t len);
-  APIError write_raw_(const struct iovec *iov, int iovcnt);
+  inline APIError write_raw_(const struct iovec *iov, int iovcnt) {
+    return APIFrameHelper::write_raw_(iov, iovcnt, socket_.get(), tx_buf_, info_, state_, State::FAILED);
+  }
   APIError init_handshake_();
   APIError check_handshake_finished_();
   void send_explicit_handshake_reject_(const std::string &reason);
@@ -111,6 +139,9 @@ class APINoiseFrameHelper : public APIFrameHelper {
   std::unique_ptr<socket::Socket> socket_;
 
   std::string info_;
+  // Fixed-size header buffer for noise protocol:
+  // 1 byte for indicator + 2 bytes for message size (16-bit value, not varint)
+  // Note: Maximum message size is 65535, with a limit of 128 bytes during handshake phase
   uint8_t rx_header_buf_[3];
   size_t rx_header_buf_len_ = 0;
   std::vector<uint8_t> rx_buf_;
@@ -141,13 +172,20 @@ class APINoiseFrameHelper : public APIFrameHelper {
 #ifdef USE_API_PLAINTEXT
 class APIPlaintextFrameHelper : public APIFrameHelper {
  public:
-  APIPlaintextFrameHelper(std::unique_ptr<socket::Socket> socket) : socket_(std::move(socket)) {}
+  APIPlaintextFrameHelper(std::unique_ptr<socket::Socket> socket) : socket_(std::move(socket)) {
+    // Plaintext header structure (worst case):
+    // Pos 0: indicator (0x00)
+    // Pos 1-3: payload size varint (up to 3 bytes)
+    // Pos 4-5: message type varint (up to 2 bytes)
+    // Pos 6+: actual payload data
+    frame_header_padding_ = 6;
+  }
   ~APIPlaintextFrameHelper() override = default;
   APIError init() override;
   APIError loop() override;
   APIError read_packet(ReadPacketBuffer *buffer) override;
   bool can_write_without_blocking() override;
-  APIError write_packet(uint16_t type, const uint8_t *payload, size_t len) override;
+  APIError write_protobuf_packet(uint16_t type, ProtoWriteBuffer buffer) override;
   std::string getpeername() override { return this->socket_->getpeername(); }
   int getpeername(struct sockaddr *addr, socklen_t *addrlen) override {
     return this->socket_->getpeername(addr, addrlen);
@@ -156,6 +194,10 @@ class APIPlaintextFrameHelper : public APIFrameHelper {
   APIError shutdown(int how) override;
   // Give this helper a name for logging
   void set_log_info(std::string info) override { info_ = std::move(info); }
+  // Get the frame header padding required by this protocol
+  uint8_t frame_header_padding() override { return frame_header_padding_; }
+  // Get the frame footer size required by this protocol
+  uint8_t frame_footer_size() override { return frame_footer_size_; }
 
  protected:
   struct ParsedFrame {
@@ -164,12 +206,23 @@ class APIPlaintextFrameHelper : public APIFrameHelper {
 
   APIError try_read_frame_(ParsedFrame *frame);
   APIError try_send_tx_buf_();
-  APIError write_raw_(const struct iovec *iov, int iovcnt);
+  inline APIError write_raw_(const struct iovec *iov, int iovcnt) {
+    return APIFrameHelper::write_raw_(iov, iovcnt, socket_.get(), tx_buf_, info_, state_, State::FAILED);
+  }
 
   std::unique_ptr<socket::Socket> socket_;
 
   std::string info_;
-  std::vector<uint8_t> rx_header_buf_;
+  // Fixed-size header buffer for plaintext protocol:
+  // We only need space for the two varints since we validate the indicator byte separately.
+  // To match noise protocol's maximum message size (65535), we need:
+  // 3 bytes for message size varint (supports up to 2097151) + 2 bytes for message type varint
+  //
+  // While varints could theoretically be up to 10 bytes each for 64-bit values,
+  // attempting to process messages with headers that large would likely crash the
+  // ESP32 due to memory constraints.
+  uint8_t rx_header_buf_[5];  // 5 bytes for varints (3 for size + 2 for type)
+  uint8_t rx_header_buf_pos_ = 0;
   bool rx_header_parsed_ = false;
   uint32_t rx_header_parsed_type_ = 0;
   uint32_t rx_header_parsed_len_ = 0;