From e26b5874d76332aa35125e3be434a9d7ab525d3a Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Mon, 27 Oct 2025 15:07:31 -0500
Subject: [PATCH] [api] Register user services with initializer_list (#11545)

---
 esphome/components/api/__init__.py         | 10 +++++++++-
 esphome/components/api/api_server.h        |  6 ++++++
 esphome/components/api/custom_api_device.h | 12 ++++++++++++
 esphome/core/defines.h                     |  1 +
 4 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/esphome/components/api/__init__.py b/esphome/components/api/__init__.py
index e91e922204..363f5b73e1 100644
--- a/esphome/components/api/__init__.py
+++ b/esphome/components/api/__init__.py
@@ -258,6 +258,10 @@ async def to_code(config):
     if config.get(CONF_ACTIONS) or config[CONF_CUSTOM_SERVICES]:
         cg.add_define("USE_API_SERVICES")
 
+    # Set USE_API_CUSTOM_SERVICES if external components need dynamic service registration
+    if config[CONF_CUSTOM_SERVICES]:
+        cg.add_define("USE_API_CUSTOM_SERVICES")
+
     if config[CONF_HOMEASSISTANT_SERVICES]:
         cg.add_define("USE_API_HOMEASSISTANT_SERVICES")
 
@@ -265,6 +269,8 @@ async def to_code(config):
         cg.add_define("USE_API_HOMEASSISTANT_STATES")
 
     if actions := config.get(CONF_ACTIONS, []):
+        # Collect all triggers first, then register all at once with initializer_list
+        triggers: list[cg.Pvariable] = []
         for conf in actions:
             template_args = []
             func_args = []
@@ -278,8 +284,10 @@ async def to_code(config):
             trigger = cg.new_Pvariable(
                 conf[CONF_TRIGGER_ID], templ, conf[CONF_ACTION], service_arg_names
             )
-            cg.add(var.register_user_service(trigger))
+            triggers.append(trigger)
             await automation.build_automation(trigger, func_args, conf)
+        # Register all services at once - single allocation, no reallocations
+        cg.add(var.initialize_user_services(triggers))
 
     if CONF_ON_CLIENT_CONNECTED in config:
         cg.add_define("USE_API_CLIENT_CONNECTED_TRIGGER")
diff --git a/esphome/components/api/api_server.h b/esphome/components/api/api_server.h
index e0e23301d0..d29181250e 100644
--- a/esphome/components/api/api_server.h
+++ b/esphome/components/api/api_server.h
@@ -125,8 +125,14 @@ class APIServer : public Component, public Controller {
 #endif  // USE_API_HOMEASSISTANT_ACTION_RESPONSES
 #endif  // USE_API_HOMEASSISTANT_SERVICES
 #ifdef USE_API_SERVICES
+  void initialize_user_services(std::initializer_list<UserServiceDescriptor *> services) {
+    this->user_services_.assign(services);
+  }
+#ifdef USE_API_CUSTOM_SERVICES
+  // Only compile push_back method when custom_services: true (external components)
   void register_user_service(UserServiceDescriptor *descriptor) { this->user_services_.push_back(descriptor); }
 #endif
+#endif
 #ifdef USE_HOMEASSISTANT_TIME
   void request_time();
 #endif
diff --git a/esphome/components/api/custom_api_device.h b/esphome/components/api/custom_api_device.h
index 711eba2444..d34ccfa0ce 100644
--- a/esphome/components/api/custom_api_device.h
+++ b/esphome/components/api/custom_api_device.h
@@ -53,8 +53,14 @@ class CustomAPIDevice {
   template<typename T, typename... Ts>
   void register_service(void (T::*callback)(Ts...), const std::string &name,
                         const std::array<std::string, sizeof...(Ts)> &arg_names) {
+#ifdef USE_API_CUSTOM_SERVICES
     auto *service = new CustomAPIDeviceService<T, Ts...>(name, arg_names, (T *) this, callback);  // NOLINT
     global_api_server->register_user_service(service);
+#else
+    static_assert(
+        sizeof(T) == 0,
+        "register_service() requires 'custom_services: true' in the 'api:' section of your YAML configuration");
+#endif
   }
 #else
   template<typename T, typename... Ts>
@@ -86,8 +92,14 @@ class CustomAPIDevice {
    */
 #ifdef USE_API_SERVICES
   template<typename T> void register_service(void (T::*callback)(), const std::string &name) {
+#ifdef USE_API_CUSTOM_SERVICES
     auto *service = new CustomAPIDeviceService<T>(name, {}, (T *) this, callback);  // NOLINT
     global_api_server->register_user_service(service);
+#else
+    static_assert(
+        sizeof(T) == 0,
+        "register_service() requires 'custom_services: true' in the 'api:' section of your YAML configuration");
+#endif
   }
 #else
   template<typename T> void register_service(void (T::*callback)(), const std::string &name) {
diff --git a/esphome/core/defines.h b/esphome/core/defines.h
index 8095ffed4a..97e766455a 100644
--- a/esphome/core/defines.h
+++ b/esphome/core/defines.h
@@ -123,6 +123,7 @@
 #define USE_API_NOISE
 #define USE_API_PLAINTEXT
 #define USE_API_SERVICES
+#define USE_API_CUSTOM_SERVICES
 #define API_MAX_SEND_QUEUE 8
 #define USE_MD5
 #define USE_SHA256