api_server.h

Go to the documentation of this file.

#pragma once
 
#include "esphome/core/defines.h"
#ifdef USE_API
#include "api_buffer.h"
// Must precede clients_ so APIConnection is complete for default_delete (libc++).
#include "api_connection.h"
#if defined(USE_API_NOISE) || defined(USE_NOISE_SPARE_EPHEMERAL)
// Only present in the build when the noise component is loaded
#include "esphome/components/noise/noise.h"
#endif
#include "api_pb2.h"
#include "api_pb2_service.h"
#include "api_outgoing_connection.h"
#include "esphome/components/socket/socket.h"
#include "esphome/core/automation.h"
#include "esphome/core/component.h"
#include "esphome/core/entity_includes.h"
#include "esphome/core/log.h"
#include "esphome/core/string_ref.h"
#ifdef USE_PROVISIONING
#include "esphome/components/provisioning/provisioning.h"
#endif
#ifdef USE_LOGGER
#include "esphome/components/logger/logger.h"
#endif
#ifdef USE_CAMERA
#include "esphome/components/camera/camera.h"
#endif
 
#include <array>
#include <memory>
#include <vector>
 
namespace esphome::api {
 
#ifdef USE_API_USER_DEFINED_ACTIONS
// Forward declaration - full definition in user_services.h
class UserServiceDescriptor;
#endif
 
#ifdef USE_API_NOISE
struct SavedNoisePsk {
  noise::psk_t psk;
} PACKED;  // NOLINT
#endif
#if defined(USE_API_NOISE) && defined(USE_OTA_ENCRYPTION_PROVISIONED)
bool load_saved_noise_psk(noise::psk_t &out);
#endif
 
class APIServer final : public Component
#ifdef USE_CAMERA
    ,
                        public camera::CameraListener
#endif
{
 public:
  APIServer();
  void setup() override;
  uint16_t get_port() const { return this->port_; }
  float get_setup_priority() const override { return setup_priority::AFTER_WIFI; }
  void loop() override;
  void dump_config() override;
  void on_shutdown() override;
  bool teardown() override;
#ifdef USE_LOGGER
  void on_log(uint8_t level, const char *tag, const char *message, size_t message_len);
#endif
#ifdef USE_CAMERA
  void on_camera_image(const std::shared_ptr<camera::CameraImage> &image) override;
#endif
  void set_port(uint16_t port) { this->port_ = port; }
  void set_reboot_timeout(uint32_t reboot_timeout) { this->reboot_timeout_ = reboot_timeout; }
  void set_batch_delay(uint16_t batch_delay) { this->batch_delay_ = batch_delay; }
  uint16_t get_batch_delay() const { return batch_delay_; }
  void set_listen_backlog(uint8_t listen_backlog) { this->listen_backlog_ = listen_backlog; }
 
  // Get reference to shared buffer for API connections
  APIBuffer &get_shared_buffer_ref() { return shared_write_buffer_; }
 
#ifdef USE_API_NOISE
#ifndef USE_API_NOISE_PSK_FROM_YAML
  // Runtime key changes exist for the provisioning path only (not lambdas);
  // with a yaml key they compile out
  bool save_noise_psk(noise::psk_t psk, bool make_active = true);
  bool clear_noise_psk(bool make_active = true);
#endif
  void set_noise_psk(const uint8_t *psk) { this->noise_ctx_.set_psk(psk); }
  noise::NoiseContext &get_noise_ctx() { return this->noise_ctx_; }
#endif  // USE_API_NOISE
#ifdef USE_API_OUTGOING_CONNECTION
  // Called by APIConnection when a client declares itself a dial-back target in its hello
  void on_outgoing_target_client(APIConnection *conn);
#endif
 
  void handle_disconnect(APIConnection *conn);
#ifdef USE_BINARY_SENSOR
  void on_binary_sensor_update(binary_sensor::BinarySensor *obj);
#endif
#ifdef USE_COVER
  void on_cover_update(cover::Cover *obj);
#endif
#ifdef USE_FAN
  void on_fan_update(fan::Fan *obj);
#endif
#ifdef USE_LIGHT
  void on_light_update(light::LightState *obj);
#endif
#ifdef USE_SENSOR
  void on_sensor_update(sensor::Sensor *obj);
#endif
#ifdef USE_SWITCH
  void on_switch_update(switch_::Switch *obj);
#endif
#ifdef USE_TEXT_SENSOR
  void on_text_sensor_update(text_sensor::TextSensor *obj);
#endif
#ifdef USE_CLIMATE
  void on_climate_update(climate::Climate *obj);
#endif
#ifdef USE_NUMBER
  void on_number_update(number::Number *obj);
#endif
#ifdef USE_DATETIME_DATE
  void on_date_update(datetime::DateEntity *obj);
#endif
#ifdef USE_DATETIME_TIME
  void on_time_update(datetime::TimeEntity *obj);
#endif
#ifdef USE_DATETIME_DATETIME
  void on_datetime_update(datetime::DateTimeEntity *obj);
#endif
#ifdef USE_TEXT
  void on_text_update(text::Text *obj);
#endif
#ifdef USE_SELECT
  void on_select_update(select::Select *obj);
#endif
#ifdef USE_LOCK
  void on_lock_update(lock::Lock *obj);
#endif
#ifdef USE_VALVE
  void on_valve_update(valve::Valve *obj);
#endif
#ifdef USE_MEDIA_PLAYER
  void on_media_player_update(media_player::MediaPlayer *obj);
#endif
#ifdef USE_WATER_HEATER
  void on_water_heater_update(water_heater::WaterHeater *obj);
#endif
#ifdef USE_API_HOMEASSISTANT_SERVICES
  void send_homeassistant_action(const HomeassistantActionRequest &call);
 
#ifdef USE_API_HOMEASSISTANT_ACTION_RESPONSES
  // Action response handling
  using ActionResponseCallback = std::function<void(const class ActionResponse &)>;
  void register_action_response_callback(uint32_t call_id, ActionResponseCallback callback);
  void handle_action_response(uint32_t call_id, bool success, StringRef error_message);
#ifdef USE_API_HOMEASSISTANT_ACTION_RESPONSES_JSON
  void handle_action_response(uint32_t call_id, bool success, StringRef error_message, const uint8_t *response_data,
                              size_t response_data_len);
#endif  // USE_API_HOMEASSISTANT_ACTION_RESPONSES_JSON
#endif  // USE_API_HOMEASSISTANT_ACTION_RESPONSES
#endif  // USE_API_HOMEASSISTANT_SERVICES
#ifdef USE_API_USER_DEFINED_ACTIONS
  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
#ifdef USE_API_USER_DEFINED_ACTION_RESPONSES
  // Action call context management - supports concurrent calls from multiple clients
  // Returns server-generated action_call_id to avoid collisions when clients use same call_id
  uint32_t register_active_action_call(uint32_t client_call_id, APIConnection *conn);
  void unregister_active_action_call(uint32_t action_call_id);
  void unregister_active_action_calls_for_connection(APIConnection *conn);
  // Send response for a specific action call (uses action_call_id, sends client_call_id in response)
  void send_action_response(uint32_t action_call_id, bool success, StringRef error_message);
#ifdef USE_API_USER_DEFINED_ACTION_RESPONSES_JSON
  void send_action_response(uint32_t action_call_id, bool success, StringRef error_message,
                            const uint8_t *response_data, size_t response_data_len);
#endif  // USE_API_USER_DEFINED_ACTION_RESPONSES_JSON
#endif  // USE_API_USER_DEFINED_ACTION_RESPONSES
#endif
#ifdef USE_HOMEASSISTANT_TIME
  void request_time();
#endif
 
#ifdef USE_ALARM_CONTROL_PANEL
  void on_alarm_control_panel_update(alarm_control_panel::AlarmControlPanel *obj);
#endif
#ifdef USE_EVENT
  void on_event(event::Event *obj);
#endif
#ifdef USE_UPDATE
  void on_update(update::UpdateEntity *obj);
#endif
#ifdef USE_ZWAVE_PROXY
  void on_zwave_proxy_request(const ZWaveProxyRequest &msg);
#endif
#ifdef USE_SERIAL_PROXY_USB_IDENTITY
  void send_serial_proxy_identity(const SerialProxyIdentity &msg);
#endif
#ifdef USE_IR_RF
  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->api_connection_count_ != 0; }
  bool is_connected_with_state_subscription() const;
  bool is_connected(bool state_subscription_only) const {
    return state_subscription_only ? this->is_connected_with_state_subscription() : this->is_connected();
  }
 
  // Range-for view over the populated slice [0, api_connection_count_). Read-only with respect
  // to ownership; callers get `const unique_ptr&` so they can invoke non-const methods on the
  // APIConnection but cannot reset/move the slot and break the count invariant.
  using APIConnectionPtr = std::unique_ptr<APIConnection>;
  class ActiveClientsView {
    const APIConnectionPtr *begin_;
    const APIConnectionPtr *end_;
 
   public:
    ActiveClientsView(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() 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)
    const char *attribute;  // Pointer to flash or nullptr (nullptr means no attribute)
    std::function<void(StringRef)> callback;
    bool once;
 
    // Dynamic storage for external components using std::string API (custom_api_device.h)
    // These are only allocated when using the std::string overload (nullptr for const char* overload)
    std::unique_ptr<std::string> entity_id_dynamic_storage;
    std::unique_ptr<std::string> attribute_dynamic_storage;
  };
 
  // New const char* overload (for internal components - zero allocation)
  void subscribe_home_assistant_state(const char *entity_id, const char *attribute, std::function<void(StringRef)> &&f);
  void get_home_assistant_state(const char *entity_id, const char *attribute, std::function<void(StringRef)> &&f);
 
  // std::string overload with StringRef callback (for custom_api_device.h with zero-allocation callback)
  void subscribe_home_assistant_state(std::string entity_id, optional<std::string> attribute,
                                      std::function<void(StringRef)> &&f);
  void get_home_assistant_state(std::string entity_id, optional<std::string> attribute,
                                std::function<void(StringRef)> &&f);
 
  // Legacy std::string overload (for custom_api_device.h - converts StringRef to std::string for callback)
  void subscribe_home_assistant_state(std::string entity_id, optional<std::string> attribute,
                                      std::function<void(const std::string &)> &&f);
  void get_home_assistant_state(std::string entity_id, optional<std::string> attribute,
                                std::function<void(const std::string &)> &&f);
 
  const std::vector<HomeAssistantStateSubscription> &get_state_subs() const;
#endif
#ifdef USE_API_USER_DEFINED_ACTIONS
  const std::vector<UserServiceDescriptor *> &get_user_services() const { return this->user_services_; }
#endif
 
#ifdef USE_API_CLIENT_CONNECTED_TRIGGER
  Trigger<std::string, std::string> *get_client_connected_trigger() { return &this->client_connected_trigger_; }
#endif
#ifdef USE_API_CLIENT_DISCONNECTED_TRIGGER
  Trigger<std::string, std::string> *get_client_disconnected_trigger() { return &this->client_disconnected_trigger_; }
#endif
 
 protected:
  // Accept incoming socket connections. Only called when socket has pending connections.
  void __attribute__((noinline)) accept_new_connections_();
  APIConnection *add_client_(std::unique_ptr<socket::Socket> sock);
  bool at_client_limit_() const { return this->api_connection_count_ >= MAX_API_CONNECTIONS; }
#ifdef USE_API_OUTGOING_CONNECTION
  // Returns the new connection, or nullptr (socket dropped) when at the limit
  APIConnection *add_outgoing_client_(std::unique_ptr<socket::Socket> sock);
  bool has_outgoing_target_client_() const { return this->outgoing_target_count_ != 0; }
  friend class OutgoingConnectionManager;
#endif
  // 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_PROVISIONING
  // True while a configured provisioning window is still pending (the device is
  // unprovisioned). Suppresses the reboot timeout and its warning so the device is
  // not auto-rebooted while waiting to be provisioned. False when no provisioning
  // window is configured.
  bool provisioning_pending_() const {
    return provisioning::global_provisioning_manager != nullptr &&
           provisioning::global_provisioning_manager->window_pending();
  }
#else
  bool provisioning_pending_() const { return false; }
#endif
 
#ifdef USE_API_NOISE
#ifndef USE_API_NOISE_PSK_FROM_YAML
  bool update_noise_psk_(const SavedNoisePsk &new_psk, const LogString *save_log_msg, const LogString *fail_log_msg,
                         bool make_active);
  // Load saved PSK from preferences and apply it. Returns true on success.
  bool load_and_apply_noise_psk_();
#endif  // USE_API_NOISE_PSK_FROM_YAML
#endif  // USE_API_NOISE
#ifdef USE_API_HOMEASSISTANT_STATES
  // Helper methods to reduce code duplication
  void add_state_subscription_(const char *entity_id, const char *attribute, std::function<void(StringRef)> &&f,
                               bool once);
  void add_state_subscription_(std::string entity_id, optional<std::string> attribute,
                               std::function<void(StringRef)> &&f, bool once);
  // Legacy helper: wraps std::string callback and delegates to StringRef version
  void add_state_subscription_(std::string entity_id, optional<std::string> attribute,
                               std::function<void(const std::string &)> &&f, bool once);
#endif  // USE_API_HOMEASSISTANT_STATES
  // No explicit close() needed — listen sockets have no active connections on
  // failure/shutdown. Destructor handles fd cleanup (close or abort per platform).
  inline void destroy_socket_() {
    delete this->socket_;
    this->socket_ = nullptr;
  }
  void socket_failed_(const LogString *msg);
  // Pointers and pointer-like types first (4 bytes each)
  socket::ListenSocket *socket_{nullptr};
#ifdef USE_API_CLIENT_CONNECTED_TRIGGER
  Trigger<std::string, std::string> client_connected_trigger_;
#endif
#ifdef USE_API_CLIENT_DISCONNECTED_TRIGGER
  Trigger<std::string, std::string> client_disconnected_trigger_;
#endif
 
  // 4-byte aligned types
  uint32_t reboot_timeout_{900000};  // Keep in sync with DEFAULT_REBOOT_TIMEOUT in __init__.py
  uint32_t last_connected_{0};
 
  // Slots [0, api_connection_count_) are populated; trailing slots are always nullptr.
  std::array<APIConnectionPtr, MAX_API_CONNECTIONS> clients_{};
  // Vectors and strings (12 bytes each on 32-bit)
  // 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
  // since the buffer would almost always reallocate on first use.
  APIBuffer shared_write_buffer_;
#ifdef USE_API_HOMEASSISTANT_STATES
  std::vector<HomeAssistantStateSubscription> state_subs_;
#endif
#ifdef USE_API_USER_DEFINED_ACTIONS
  std::vector<UserServiceDescriptor *> user_services_;
#ifdef USE_API_USER_DEFINED_ACTION_RESPONSES
  // Active action calls - supports concurrent calls from multiple clients
  // Uses server-generated action_call_id to avoid collisions when multiple clients use same call_id
  struct ActiveActionCall {
    uint32_t action_call_id;  // Server-generated unique ID (passed to actions)
    uint32_t client_call_id;  // Client's original call_id (used in response)
    APIConnection *connection;
  };
  std::vector<ActiveActionCall> active_action_calls_;
  uint32_t next_action_call_id_{1};  // Counter for generating unique action_call_ids
#endif                               // USE_API_USER_DEFINED_ACTION_RESPONSES
#endif
#ifdef USE_API_HOMEASSISTANT_ACTION_RESPONSES
  struct PendingActionResponse {
    uint32_t call_id;
    ActionResponseCallback callback;
  };
  std::vector<PendingActionResponse> action_response_callbacks_;
#endif
 
  // Group smaller types together
  uint16_t port_{6053};        // Keep in sync with DEFAULT_PORT in __init__.py
  uint16_t batch_delay_{100};  // Keep in sync with DEFAULT_BATCH_DELAY in __init__.py
  uint8_t listen_backlog_{4};  // Keep in sync with DEFAULT_LISTEN_BACKLOG in __init__.py
  bool shutting_down_ = false;
  uint8_t api_connection_count_{0};
#ifdef USE_API_OUTGOING_CONNECTION
  // Connected clients whose hello declared them a dial-back target
  uint8_t outgoing_target_count_{0};
#endif
#if defined(USE_PROVISIONING) && defined(USE_API_NOISE)
  // Index assigned by the provisioning manager for reporting this transport's state.
  uint8_t provisioning_source_{0};
#endif
 
#ifdef USE_NOISE_SPARE_EPHEMERAL
  void refill_spare_ephemeral_();
#endif
#ifdef USE_API_NOISE
  noise::NoiseContext noise_ctx_;
#ifndef USE_API_NOISE_PSK_FROM_YAML
  SavedNoisePsk saved_psk_{};  // backs noise_ctx_ for a runtime provisioned key
#endif
  ESPPreferenceObject noise_pref_;
#endif  // USE_API_NOISE
#ifdef USE_API_OUTGOING_CONNECTION
  OutgoingConnectionManager outgoing_conn_;
#endif
};
 
extern APIServer *global_api_server;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
 
}  // namespace esphome::api
#endif