[api] Add outgoing connections so the device can dial Home Assistant (or anything that implements native API) (#18919)

Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>
2026-10-14 10:12:52 +00:00 · 2026-10-07 16:22:14 +13:00
parent f3f79c301b
commit 0e04b230fe
25 changed files with 1217 additions and 60 deletions
@@ -56,7 +56,12 @@ APIServer::APIServer() { global_api_server = this; }
 void APIServer::socket_failed_(const LogString *msg) {
  ESP_LOGW(TAG, "Socket %s: errno %d", LOG_STR_ARG(msg), errno);
  this->destroy_socket_();
+#ifdef USE_API_OUTGOING_CONNECTION
+  // Dial-out needs no listener; degrade instead of stopping the component
+  this->status_set_error(LOG_STR("listen socket failed"));
+#else
  this->mark_failed();
+#endif
 }

 void APIServer::setup() {
@@ -72,43 +77,6 @@ void APIServer::setup() {
 #endif
 #endif

-  this->socket_ = socket::socket_ip_loop_monitored(SOCK_STREAM, 0).release();  // monitored for incoming connections
-  if (this->socket_ == nullptr) {
-    this->socket_failed_(LOG_STR("creation"));
-    return;
-  }
-  int enable = 1;
-  int err = this->socket_->setsockopt(SOL_SOCKET, SO_REUSEADDR, &enable, sizeof(int));
-  if (err != 0) {
-    ESP_LOGW(TAG, "Socket reuseaddr: errno %d", errno);
-    // we can still continue
-  }
-  err = this->socket_->setblocking(false);
-  if (err != 0) {
-    this->socket_failed_(LOG_STR("nonblocking"));
-    return;
-  }
-
-  struct sockaddr_storage server;
-
-  socklen_t sl = socket::set_sockaddr_any((struct sockaddr *) &server, sizeof(server), this->port_);
-  if (sl == 0) {
-    this->socket_failed_(LOG_STR("set sockaddr"));
-    return;
-  }
-
-  err = this->socket_->bind((struct sockaddr *) &server, sl);
-  if (err != 0) {
-    this->socket_failed_(LOG_STR("bind"));
-    return;
-  }
-
-  err = this->socket_->listen(this->listen_backlog_);
-  if (err != 0) {
-    this->socket_failed_(LOG_STR("listen"));
-    return;
-  }
-
 #ifdef USE_LOGGER
  if (logger::global_logger != nullptr) {
    logger::global_logger->add_log_callback(
@@ -154,6 +122,47 @@ void APIServer::setup() {
  if (this->reboot_timeout_ != 0 && !this->provisioning_pending_()) {
    this->status_set_warning(LOG_STR("waiting for client connection"));
  }
+#ifdef USE_API_OUTGOING_CONNECTION
+  this->outgoing_conn_.setup();
+#endif
+
+  // Listener last: on failure socket_failed_() returns early, and an
+  // outgoing_connection build keeps dialing out without one
+  this->socket_ = socket::socket_ip_loop_monitored(SOCK_STREAM, 0).release();  // monitored for incoming connections
+  if (this->socket_ == nullptr) {
+    this->socket_failed_(LOG_STR("creation"));
+    return;
+  }
+  int enable = 1;
+  int err = this->socket_->setsockopt(SOL_SOCKET, SO_REUSEADDR, &enable, sizeof(int));
+  if (err != 0) {
+    ESP_LOGW(TAG, "Socket reuseaddr: errno %d", errno);
+    // we can still continue
+  }
+  err = this->socket_->setblocking(false);
+  if (err != 0) {
+    this->socket_failed_(LOG_STR("nonblocking"));
+    return;
+  }
+
+  struct sockaddr_storage server;
+
+  socklen_t sl = socket::set_sockaddr_any((struct sockaddr *) &server, sizeof(server), this->port_);
+  if (sl == 0) {
+    this->socket_failed_(LOG_STR("set sockaddr"));
+    return;
+  }
+
+  err = this->socket_->bind((struct sockaddr *) &server, sl);
+  if (err != 0) {
+    this->socket_failed_(LOG_STR("bind"));
+    return;
+  }
+
+  err = this->socket_->listen(this->listen_backlog_);
+  if (err != 0) {
+    this->socket_failed_(LOG_STR("listen"));
+  }
 }

 void APIServer::loop() {
@@ -169,6 +178,12 @@ void APIServer::loop() {
  }
 #endif

+#ifdef USE_API_OUTGOING_CONNECTION
+  if (!this->shutting_down_) {
+    this->outgoing_conn_.loop(this);
+  }
+#endif
+
  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).
@@ -241,6 +256,15 @@ void APIServer::remove_client_(uint8_t client_index) {
  std::string client_peername(client->get_peername_to(peername_buf));
 #endif

+  // Read before the swap-and-reset below destroys the connection
+  const bool was_authenticated = client->is_authenticated();
+#ifdef USE_API_OUTGOING_CONNECTION
+  if (client->flags_.outgoing_connection_target) {
+    this->outgoing_target_count_--;
+  }
+  this->outgoing_conn_.on_client_removed(client.get(), was_authenticated);
+#endif
+
  // Close socket now (was deferred from on_fatal_error to allow getpeername)
  client->helper_->close();

@@ -259,9 +283,15 @@ void APIServer::remove_client_(uint8_t client_index) {

  // Last client disconnected - set warning and start tracking for reboot timeout
  // (suppressed while provisioning is pending - see loop()).
+  // Refresh on every authenticated removal, not just the last one, so an
+  // unauthenticated straggler removed later (e.g. a port scan, or a dial to
+  // a host that accepts TCP but never speaks the API) cannot discard a
+  // healthy session's timestamp and trigger a spurious reboot
+  if (was_authenticated) {
+    this->last_connected_ = App.get_loop_component_start_time();
+  }
  if (this->api_connection_count_ == 0 && this->reboot_timeout_ != 0 && !this->provisioning_pending_()) {
    this->status_set_warning(LOG_STR("waiting for client connection"));
-    this->last_connected_ = App.get_loop_component_start_time();
  }

 #ifdef USE_API_CLIENT_DISCONNECTED_TRIGGER
@@ -283,7 +313,7 @@ void __attribute__((flatten)) APIServer::accept_new_connections_() {
    sock->getpeername_to(peername);

    // Check if we're at the connection limit
-    if (this->api_connection_count_ >= MAX_API_CONNECTIONS) {
+    if (this->at_client_limit_()) {
      ESP_LOGW(TAG, "Max connections (%d), rejecting %s", MAX_API_CONNECTIONS, peername);
      // Immediately close - socket destructor will handle cleanup
      sock.reset();
@@ -292,18 +322,47 @@ void __attribute__((flatten)) APIServer::accept_new_connections_() {

    ESP_LOGD(TAG, "Accept %s", peername);

-    auto *conn = new APIConnection(std::move(sock), this);
-    this->clients_[this->api_connection_count_++].reset(conn);
-    conn->start();
-
-    // First client connected - clear warning and update timestamp
-    if (this->api_connection_count_ == 1 && this->reboot_timeout_ != 0 && !this->provisioning_pending_()) {
-      this->status_clear_warning();
-      this->last_connected_ = App.get_loop_component_start_time();
-    }
+    this->add_client_(std::move(sock));
  }
 }

+APIConnection *APIServer::add_client_(std::unique_ptr<socket::Socket> sock) {
+  auto *conn = new APIConnection(std::move(sock), this);  // NOLINT(cppcoreguidelines-owning-memory)
+  this->clients_[this->api_connection_count_++].reset(conn);
+  conn->start();
+
+  // First client connected - clear warning. The reboot watchdog timestamp is
+  // refreshed when an authenticated client is removed (see remove_client_),
+  // never on bare TCP connects.
+  if (this->api_connection_count_ == 1 && this->reboot_timeout_ != 0 && !this->provisioning_pending_()) {
+    this->status_clear_warning();
+  }
+  return conn;
+}
+
+#ifdef USE_API_OUTGOING_CONNECTION
+APIConnection *APIServer::add_outgoing_client_(std::unique_ptr<socket::Socket> sock) {
+  // Re-check at the handoff: inbound clients may have taken the last slot and
+  // the PSK may have been cleared since the dial started (mark_outgoing()
+  // needs the noise helper)
+  const bool at_limit = this->at_client_limit_();
+  if (at_limit || !this->noise_ctx_.has_psk()) {
+    ESP_LOGW(TAG, "Dropping outgoing connection (%s)",
+             at_limit ? LOG_STR_LITERAL("max connections") : LOG_STR_LITERAL("no key"));
+    return nullptr;
+  }
+  auto *conn = this->add_client_(std::move(sock));
+  // After start(): sends our server hello first so the peer can pick the key
+  conn->mark_outgoing();
+  return conn;
+}
+
+void APIServer::on_outgoing_target_client(APIConnection *conn) {
+  this->outgoing_target_count_++;
+  this->outgoing_conn_.on_target_client(conn);
+}
+#endif
+
 void APIServer::dump_config() {
  char addr_buf[network::USE_ADDRESS_BUFFER_SIZE];
  ESP_LOGCONFIG(TAG,
@@ -320,6 +379,9 @@ void APIServer::dump_config() {
 #else
  ESP_LOGCONFIG(TAG, "  Noise encryption: NO");
 #endif
+#ifdef USE_API_OUTGOING_CONNECTION
+  this->outgoing_conn_.dump_config();
+#endif
 }

 void APIServer::handle_disconnect(APIConnection *conn) {}
@@ -616,6 +678,8 @@ bool APIServer::update_noise_psk_(const SavedNoisePsk &new_psk, const LogString
        if (!c->send_message(req)) {
          API_LOG_MSG_DROPPED(TAG, "Disconnect request");
        }
+        // Force it: a session from before the key was active must not survive
+        c->flags_.next_close = true;
      }
    });
  }
@@ -717,6 +781,9 @@ void APIServer::on_shutdown() {

  // Close the listening socket to prevent new connections
  this->destroy_socket_();
+#ifdef USE_API_OUTGOING_CONNECTION
+  this->outgoing_conn_.on_shutdown();
+#endif

  // Change batch delay to 5ms for quick flushing during shutdown
  this->batch_delay_ = 5;