[api] Replace clients_ std::vector with compile-time std::array + uint8_t count

Convert APIServer's client container from
`std::vector<std::unique_ptr<APIConnection>>` to a compile-time sized
`std::array<..., MAX_API_CONNECTIONS>` with an inline `uint8_t
api_connection_count_` tracking the active slice.

Why:
- Eliminates a persistent heap-held buffer (one of APIServer's
  fragmentation sources). The vector grows via doubling reallocations
  (0 -> 1 -> 2 -> 4 -> 8) and keeps its capacity for the life of the
  process.
- Kills ~100-150 bytes of `_M_realloc_insert` template instantiation
  per build (measured: -92 B on ESP32-S3, -152 B on ESP8266).
- is_connected() becomes `api_connection_count_ != 0` — a single-byte
  load, down from two pointer loads + compare.
- The count lives in what was already 1 byte of padding after
  shutting_down_, replacing the removed max_connections_ runtime
  setter. Zero size overhead in that slot.
- Max connections is now a compile-time constant via
  cg.add_define("MAX_API_CONNECTIONS", ...), so the accept cap check
  and the array size derive from the same value.

Also lower default max_connections on mid/high-RAM platforms from 8 to
6. With a compile-time array, every slot costs 4 bytes of static RAM
whether a connection ever uses it or not — 6 covers HA + dashboard +
spares without paying the full 8-slot static cost. esp8266 stays at 4,
rp2040 stays at 4.

Mechanical churn:
- 13 `for (auto &c : this->clients_)` -> `for (auto &c : this->active_clients())`,
  where active_clients() returns a pointer-range view over the active
  slice.
- `.empty()` / `.size()` -> comparisons against api_connection_count_.
- `.emplace_back()` / `.pop_back()` / `.back()` rewritten in the
  swap-and-pop path to index into the array and reset() the freed slot
  (maintains the invariant that slots [count, N) are always nullptr).

Measured on ESP32-S3 (zwave-proxy-seeedw5500, N=6):
  RAM: 32464 -> 32480 B  (+16 B static, but no heap buffer)
  Flash: 469011 -> 468919 B  (-92 B)

Measured on ESP8266 (basic8266, N=4):
  RAM: 29268 -> 29268 B  (unchanged at this granularity)
  Flash: 323847 -> 323695 B  (-152 B)

esphome/components/api/__init__.py

@@ -291,12 +291,12 @@ CONFIG_SCHEMA = cv.All(
             cv.SplitDefault(
                 CONF_MAX_CONNECTIONS,
                 esp8266=4,  # ~40KB free RAM, each connection uses ~500-1000 bytes
-                esp32=8,  # 520KB RAM available
+                esp32=6,  # 520KB RAM — 6 is enough for HA + dashboard + a couple of spares
                 rp2040=4,  # 264KB RAM but LWIP constraints
-                bk72xx=8,  # Moderate RAM
-                rtl87xx=8,  # Moderate RAM
-                host=8,  # Abundant resources
-                ln882x=8,  # Moderate RAM
+                bk72xx=6,  # Moderate RAM
+                rtl87xx=6,  # Moderate RAM
+                host=6,  # Abundant resources, but array is compile-time so keep it reasonable
+                ln882x=6,  # Moderate RAM
             ): cv.int_range(min=1, max=20),
             # Maximum queued send buffers per connection before dropping connection
             # Each buffer uses ~8-12 bytes overhead plus actual message size
@@ -336,8 +336,10 @@ async def to_code(config: ConfigType) -> None:
     cg.add(var.set_batch_delay(config[CONF_BATCH_DELAY]))
     if CONF_LISTEN_BACKLOG in config:
         cg.add(var.set_listen_backlog(config[CONF_LISTEN_BACKLOG]))
-    if CONF_MAX_CONNECTIONS in config:
-        cg.add(var.set_max_connections(config[CONF_MAX_CONNECTIONS]))
+    # MAX_API_CONNECTIONS sizes the compile-time std::array<APIConnection*, N> in APIServer.
+    # Making this a compile-time constant (rather than a runtime set_max_connections setter)
+    # eliminates the std::vector heap allocation and its reallocation machinery.
+    cg.add_define("MAX_API_CONNECTIONS", config[CONF_MAX_CONNECTIONS])
     cg.add_define("API_MAX_SEND_QUEUE", config[CONF_MAX_SEND_QUEUE])
 
     # Set USE_API_USER_DEFINED_ACTIONS if any services are enabled

esphome/components/api/api_server.cpp

@@ -118,7 +118,7 @@ void APIServer::loop() {
     this->accept_new_connections_();
   }
 
-  if (this->clients_.empty()) {
+  if (this->api_connection_count_ == 0) {
     // Check reboot timeout - done in loop to avoid scheduler heap churn
     // (cancelled scheduler items sit in heap memory until their scheduled time)
     if (this->reboot_timeout_ != 0) {
@@ -135,15 +135,15 @@ void APIServer::loop() {
   // Check network connectivity once for all clients
   if (!network::is_connected()) {
     // Network is down - disconnect all clients
-    for (auto &client : this->clients_) {
+    for (auto &client : this->active_clients()) {
       client->on_fatal_error();
       client->log_client_(ESPHOME_LOG_LEVEL_WARN, LOG_STR("Network down; disconnect"));
     }
     // Continue to process and clean up the clients below
   }
 
-  size_t client_index = 0;
-  while (client_index < this->clients_.size()) {
+  uint8_t client_index = 0;
+  while (client_index < this->api_connection_count_) {
     auto &client = this->clients_[client_index];
 
     // Common case: process active client
@@ -161,7 +161,7 @@ void APIServer::loop() {
   }
 }
 
-void APIServer::remove_client_(size_t client_index) {
+void APIServer::remove_client_(uint8_t client_index) {
   auto &client = this->clients_[client_index];
 
 #ifdef USE_API_USER_DEFINED_ACTION_RESPONSES
@@ -179,14 +179,18 @@ void APIServer::remove_client_(size_t client_index) {
   // Close socket now (was deferred from on_fatal_error to allow getpeername)
   client->helper_->close();
 
-  // Swap with the last element and pop (avoids expensive vector shifts)
-  if (client_index < this->clients_.size() - 1) {
-    std::swap(this->clients_[client_index], this->clients_.back());
+  // Swap with the last populated slot and shrink the active range by one. Resetting the
+  // now-unused trailing slot preserves the invariant that slots [api_connection_count_, N)
+  // are always nullptr, which makes debugging and defensive iteration safer.
+  const uint8_t last_index = this->api_connection_count_ - 1;
+  if (client_index < last_index) {
+    std::swap(this->clients_[client_index], this->clients_[last_index]);
   }
-  this->clients_.pop_back();
+  this->clients_[last_index].reset();
+  this->api_connection_count_--;
 
   // Last client disconnected - set warning and start tracking for reboot timeout
-  if (this->clients_.empty() && this->reboot_timeout_ != 0) {
+  if (this->api_connection_count_ == 0 && this->reboot_timeout_ != 0) {
     this->status_set_warning(LOG_STR("waiting for client connection"));
     this->last_connected_ = App.get_loop_component_start_time();
   }
@@ -210,8 +214,8 @@ void __attribute__((flatten)) APIServer::accept_new_connections_() {
     sock->getpeername_to(peername);
 
     // Check if we're at the connection limit
-    if (this->clients_.size() >= this->max_connections_) {
-      ESP_LOGW(TAG, "Max connections (%d), rejecting %s", this->max_connections_, peername);
+    if (this->api_connection_count_ >= MAX_API_CONNECTIONS) {
+      ESP_LOGW(TAG, "Max connections (%d), rejecting %s", MAX_API_CONNECTIONS, peername);
       // Immediately close - socket destructor will handle cleanup
       sock.reset();
       continue;
@@ -220,11 +224,11 @@ void __attribute__((flatten)) APIServer::accept_new_connections_() {
     ESP_LOGD(TAG, "Accept %s", peername);
 
     auto *conn = new APIConnection(std::move(sock), this);
-    this->clients_.emplace_back(conn);
+    this->clients_[this->api_connection_count_++].reset(conn);
     conn->start();
 
     // First client connected - clear warning and update timestamp
-    if (this->clients_.size() == 1 && this->reboot_timeout_ != 0) {
+    if (this->api_connection_count_ == 1 && this->reboot_timeout_ != 0) {
       this->status_clear_warning();
       this->last_connected_ = App.get_loop_component_start_time();
     }
@@ -237,7 +241,7 @@ void APIServer::dump_config() {
                 "  Address: %s:%u\n"
                 "  Listen backlog: %u\n"
                 "  Max connections: %u",
-                network::get_use_address(), this->port_, this->listen_backlog_, this->max_connections_);
+                network::get_use_address(), this->port_, this->listen_backlog_, MAX_API_CONNECTIONS);
 #ifdef USE_API_NOISE
   ESP_LOGCONFIG(TAG, "  Noise encryption: %s", YESNO(this->noise_ctx_.has_psk()));
   if (!this->noise_ctx_.has_psk()) {
@@ -255,7 +259,7 @@ void APIServer::handle_disconnect(APIConnection *conn) {}
   void APIServer::on_##entity_name##_update(entity_type *obj) { /* NOLINT(bugprone-macro-parentheses) */ \
     if (obj->is_internal()) \
       return; \
-    for (auto &c : this->clients_) { \
+    for (auto &c : this->active_clients()) { \
       if (c->flags_.state_subscription) \
         c->send_##entity_name##_state(obj); \
     } \
@@ -337,7 +341,7 @@ API_DISPATCH_UPDATE(water_heater::WaterHeater, water_heater)
 void APIServer::on_event(event::Event *obj) {
   if (obj->is_internal())
     return;
-  for (auto &c : this->clients_) {
+  for (auto &c : this->active_clients()) {
     if (c->flags_.state_subscription)
       c->send_event(obj);
   }
@@ -349,7 +353,7 @@ void APIServer::on_event(event::Event *obj) {
 void APIServer::on_update(update::UpdateEntity *obj) {
   if (obj->is_internal())
     return;
-  for (auto &c : this->clients_) {
+  for (auto &c : this->active_clients()) {
     if (c->flags_.state_subscription)
       c->send_update_state(obj);
   }
@@ -360,7 +364,7 @@ void APIServer::on_update(update::UpdateEntity *obj) {
 void APIServer::on_zwave_proxy_request(const ZWaveProxyRequest &msg) {
   // We could add code to manage a second subscription type, but, since this message type is
   //  very infrequent and small, we simply send it to all clients
-  for (auto &c : this->clients_)
+  for (auto &c : this->active_clients())
     c->send_message(msg);
 }
 #endif
@@ -375,7 +379,7 @@ void APIServer::send_infrared_rf_receive_event([[maybe_unused]] uint32_t device_
   resp.key = key;
   resp.timings = timings;
 
-  for (auto &c : this->clients_)
+  for (auto &c : this->active_clients())
     c->send_infrared_rf_receive_event(resp);
 }
 #endif
@@ -392,7 +396,7 @@ void APIServer::set_batch_delay(uint16_t batch_delay) { this->batch_delay_ = bat
 
 #ifdef USE_API_HOMEASSISTANT_SERVICES
 void APIServer::send_homeassistant_action(const HomeassistantActionRequest &call) {
-  for (auto &client : this->clients_) {
+  for (auto &client : this->active_clients()) {
     client->send_homeassistant_action(call);
   }
 }
@@ -532,7 +536,7 @@ bool APIServer::update_noise_psk_(const SavedNoisePsk &new_psk, const LogString
         return;
       }
       ESP_LOGW(TAG, "Disconnecting all clients to reset PSK");
-      for (auto &c : this->clients_) {
+      for (auto &c : this->active_clients()) {
         DisconnectRequest req;
         c->send_message(req);
       }
@@ -583,7 +587,7 @@ bool APIServer::clear_noise_psk(bool make_active) {
 
 #ifdef USE_HOMEASSISTANT_TIME
 void APIServer::request_time() {
-  for (auto &client : this->clients_) {
+  for (auto &client : this->active_clients()) {
     if (!client->flags_.remove && client->is_authenticated()) {
       client->send_time_request();
       return;  // Only request from one client to avoid clock conflicts
@@ -593,7 +597,7 @@ void APIServer::request_time() {
 #endif
 
 bool APIServer::is_connected_with_state_subscription() const {
-  for (const auto &client : this->clients_) {
+  for (const auto &client : this->active_clients()) {
     if (client->flags_.state_subscription) {
       return true;
     }
@@ -609,7 +613,7 @@ void APIServer::on_log(uint8_t level, const char *tag, const char *message, size
     // we would be filling a buffer we are trying to clear
     return;
   }
-  for (auto &c : this->clients_) {
+  for (auto &c : this->active_clients()) {
     if (!c->flags_.remove && c->get_log_subscription_level() >= level)
       c->try_send_log_message(level, tag, message, message_len);
   }
@@ -618,7 +622,7 @@ void APIServer::on_log(uint8_t level, const char *tag, const char *message, size
 
 #ifdef USE_CAMERA
 void APIServer::on_camera_image(const std::shared_ptr<camera::CameraImage> &image) {
-  for (auto &c : this->clients_) {
+  for (auto &c : this->active_clients()) {
     if (!c->flags_.remove)
       c->set_camera_state(image);
   }
@@ -635,7 +639,7 @@ void APIServer::on_shutdown() {
   this->batch_delay_ = 5;
 
   // Send disconnect requests to all connected clients
-  for (auto &c : this->clients_) {
+  for (auto &c : this->active_clients()) {
     DisconnectRequest req;
     if (!c->send_message(req)) {
       // If we can't send the disconnect request directly (tx_buffer full),
@@ -653,7 +657,7 @@ bool APIServer::teardown() {
   this->loop();
 
   // Return true only when all clients have been torn down
-  return this->clients_.empty();
+  return this->api_connection_count_ == 0;
 }
 
 #ifdef USE_API_USER_DEFINED_ACTION_RESPONSES

esphome/components/api/api_server.h

@@ -21,6 +21,8 @@
 #include "esphome/components/camera/camera.h"
 #endif
 
+#include <array>
+#include <memory>
 #include <vector>
 
 namespace esphome::api {
@@ -63,7 +65,8 @@ class APIServer final : public Component,
   void set_batch_delay(uint16_t batch_delay);
   uint16_t get_batch_delay() const { return batch_delay_; }
   void set_listen_backlog(uint8_t listen_backlog) { this->listen_backlog_ = listen_backlog; }
-  void set_max_connections(uint8_t max_connections) { this->max_connections_ = max_connections; }
+  // Max connections is a compile-time constant (MAX_API_CONNECTIONS) set from YAML via codegen;
+  // the array sizing and the accept-time cap both derive from it.
 
   // Get reference to shared buffer for API connections
   APIBuffer &get_shared_buffer_ref() { return shared_write_buffer_; }
@@ -186,9 +189,38 @@ class APIServer final : public Component,
   void send_infrared_rf_receive_event(uint32_t device_id, uint32_t key, const std::vector<int32_t> *timings);
 #endif
 
-  bool is_connected() const { return !this->clients_.empty(); }
+  bool is_connected() const { return this->api_connection_count_ != 0; }
   bool is_connected_with_state_subscription() const;
 
+  // View over the active (populated) slice of clients_. Use this for range-for iteration so we
+  // don't walk past api_connection_count_ into unused slots. Pointer range keeps iterator
+  // semantics equivalent to std::vector<std::unique_ptr<APIConnection>>::iterator.
+  using APIConnectionPtr = std::unique_ptr<APIConnection>;
+  class ActiveClientsView {
+    APIConnectionPtr *begin_;
+    APIConnectionPtr *end_;
+
+   public:
+    ActiveClientsView(APIConnectionPtr *b, APIConnectionPtr *e) : begin_(b), end_(e) {}
+    APIConnectionPtr *begin() { return this->begin_; }
+    APIConnectionPtr *end() { return this->end_; }
+  };
+  class ConstActiveClientsView {
+    const APIConnectionPtr *begin_;
+    const APIConnectionPtr *end_;
+
+   public:
+    ConstActiveClientsView(const APIConnectionPtr *b, const APIConnectionPtr *e) : begin_(b), end_(e) {}
+    const APIConnectionPtr *begin() const { return this->begin_; }
+    const APIConnectionPtr *end() const { return this->end_; }
+  };
+  ActiveClientsView active_clients() {
+    return {this->clients_.data(), this->clients_.data() + this->api_connection_count_};
+  }
+  ConstActiveClientsView active_clients() const {
+    return {this->clients_.data(), this->clients_.data() + this->api_connection_count_};
+  }
+
 #ifdef USE_API_HOMEASSISTANT_STATES
   struct HomeAssistantStateSubscription {
     const char *entity_id;  // Pointer to flash (internal) or heap (external)
@@ -234,8 +266,8 @@ class APIServer final : public Component,
  protected:
   // Accept incoming socket connections. Only called when socket has pending connections.
   void __attribute__((noinline)) accept_new_connections_();
-  // Remove a disconnected client by index. Swaps with last element and pops.
-  void __attribute__((noinline)) remove_client_(size_t client_index);
+  // Remove a disconnected client by index. Swaps with the last populated slot and resets it.
+  void __attribute__((noinline)) remove_client_(uint8_t client_index);
 
 #ifdef USE_API_NOISE
   bool update_noise_psk_(const SavedNoisePsk &new_psk, const LogString *save_log_msg, const LogString *fail_log_msg,
@@ -273,8 +305,12 @@ class APIServer final : public Component,
   uint32_t reboot_timeout_{300000};
   uint32_t last_connected_{0};
 
+  // Compile-time sized array of active API connections.
+  // Slots [0, api_connection_count_) are populated; slots [api_connection_count_, N) are kept as
+  // nullptr so the invariant "touching any live slot is safe" holds. No heap allocation, no
+  // std::vector reallocation machinery — eliminates a persistent heap-fragmentation source.
+  std::array<std::unique_ptr<APIConnection>, MAX_API_CONNECTIONS> clients_{};
   // Vectors and strings (12 bytes each on 32-bit)
-  std::vector<std::unique_ptr<APIConnection>> clients_;
   // Shared proto write buffer for all connections.
   // Not pre-allocated: all send paths call prepare_first_message_buffer() which
   // reserves the exact needed size. Pre-allocating here would cause heap fragmentation
@@ -309,10 +345,13 @@ class APIServer final : public Component,
   uint16_t port_{6053};
   uint16_t batch_delay_{100};
   // Connection limits - these defaults will be overridden by config values
-  // from cv.SplitDefault in __init__.py which sets platform-specific defaults
+  // from cv.SplitDefault in __init__.py which sets platform-specific defaults.
   uint8_t listen_backlog_{4};
-  uint8_t max_connections_{8};
   bool shutting_down_ = false;
+  // Active-slot count for clients_ (populated slots are [0, api_connection_count_)).
+  // Placed here to fill what used to be the 1-byte padding slot — zero size overhead versus the
+  // previous layout where this was the removed max_connections_ field.
+  uint8_t api_connection_count_{0};
   // 7 bytes used, 1 byte padding
 
 #ifdef USE_API_NOISE

esphome/core/defines.h

@@ -177,6 +177,7 @@
 #define USE_API_USER_DEFINED_ACTION_RESPONSES
 #define USE_API_USER_DEFINED_ACTION_RESPONSES_JSON
 #define API_MAX_SEND_QUEUE 8
+#define MAX_API_CONNECTIONS 6
 #define USE_MD5
 #define USE_SHA256
 #define USE_MQTT