Make app database update in settings on-demand trigger (#4244)

<!-- Thank you for submitting a Pull Request and helping to improve Home
Assistant. Please complete the following sections to help the processing
and review of your changes. Please do not delete anything from this
template. -->

## Summary
<!-- Provide a brief summary of the changes you have made and most
importantly what they aim to achieve -->

## Screenshots
<!-- If this is a user-facing change not in the frontend, please include
screenshots in light and dark mode. -->

## Link to pull request in Documentation repository
<!-- Pull requests that add, change or remove functionality must have a
corresponding pull request in the Companion App Documentation repository
(https://github.com/home-assistant/companion.home-assistant). Please add
the number of this pull request after the "#" -->
Documentation: home-assistant/companion.home-assistant#

## Any other notes
<!-- If there is any other information of note, like if this Pull
Request is part of a bigger change, please include it here. -->

Author: bgoncal

Sources/App/Resources/en.lproj/Localizable.strings

@@ -1454,3 +1454,4 @@ Home Assistant is open source, advocates for privacy and runs locally in your ho
 "database_updater.toast.title" = "Updating %@";
 "database_updater.toast.syncing" = "Syncing server data...";
 "database_updater.toast.syncing_with_progress" = "Syncing server data... (%d/%d)";
+"settings.connection_section.refresh_server" = "Update server information";

Sources/App/Settings/Connection/ConnectionSettingsView.swift

@@ -275,6 +275,12 @@ struct ConnectionSettingsView: View {
                 .contentShape(Rectangle())
             }
             .buttonStyle(.plain)
+
+            Button {
+                viewModel.updateAppDatabase()
+            } label: {
+                Label(L10n.Settings.ConnectionSection.refreshServer, systemSymbol: .arrowClockwise)
+            }
         }
     }
 

Sources/App/Settings/Connection/ConnectionSettingsViewModel.swift

@@ -63,6 +63,10 @@ final class ConnectionSettingsViewModel: ObservableObject {
         }
     }
 
+    func updateAppDatabase() {
+        server.refreshAppDatabase(forceUpdate: true)
+    }
+
     // MARK: - Setup
 
     private func setupObservers() {

Sources/App/Settings/Settings/ServersListView.swift

@@ -11,6 +11,13 @@ struct ServersListView: View {
             NavigationLink(destination: ConnectionSettingsView(server: server)) {
                 HomeAssistantAccountRowView(server: server)
             }
+            .contextMenu {
+                Button {
+                    server.refreshAppDatabase(forceUpdate: true)
+                } label: {
+                    Label(L10n.Settings.ConnectionSection.refreshServer, systemSymbol: .arrowClockwise)
+                }
+            }
         }
         .onMove { source, destination in
             observer.moveServers(from: source, to: destination)

Sources/App/Settings/Settings/SettingsView.swift

@@ -9,8 +9,6 @@ struct SettingsView: View {
     @EnvironmentObject private var viewControllerProvider: ViewControllerProvider
     @StateObject private var serversObserver = ServersObserver()
 
-    @State private var appDatabaseUpdaterTask: Task<Void, Never>?
-
     var body: some View {
         Group {
             if Current.isCatalyst {
@@ -19,14 +17,6 @@ struct SettingsView: View {
                 iOSView
             }
         }
-        .onAppear {
-            appDatabaseUpdaterTask?.cancel()
-            appDatabaseUpdaterTask = Task {
-                for server in Current.servers.all {
-                    await Current.appDatabaseUpdater.update(server: server)
-                }
-            }
-        }
     }
 
     // MARK: - macOS Split View

Sources/App/WebView/WebViewController.swift

@@ -759,7 +759,7 @@ final class WebViewController: UIViewController, WKNavigationDelegate, WKUIDeleg
     /// Called after view appears and on pull to refresh to avoid blocking app launch
     private func updateDatabaseAndPanels() {
         // Update runs in background automatically, returns immediately
-        Current.appDatabaseUpdater.update(server: server)
+        Current.appDatabaseUpdater.update(server: server, forceUpdate: false)
         Current.panelsUpdater.update()
     }
 

Sources/Shared/API/Server.swift

@@ -247,3 +247,13 @@ public final class Server: Hashable, Comparable, CustomStringConvertible {
         identifier.description
     }
 }
+
+#if !os(watchOS)
+public extension Server {
+    /// Triggers a refresh of this server's data from Home Assistant
+    /// - Parameter forceUpdate: Whether to force the update regardless of cache state. Defaults to `false`.
+    func refreshAppDatabase(forceUpdate: Bool = false) {
+        Current.appDatabaseUpdater.update(server: self, forceUpdate: forceUpdate)
+    }
+}
+#endif

Sources/Shared/Environment/AppDatabaseUpdater.swift

@@ -10,7 +10,7 @@ import UIKit
 /// applies per-server throttling with backoff, and performs careful cancellation and batched DB writes.
 public protocol AppDatabaseUpdaterProtocol {
     func stop()
-    func update(server: Server)
+    func update(server: Server, forceUpdate: Bool)
 }
 
 final class AppDatabaseUpdater: AppDatabaseUpdaterProtocol {
@@ -155,9 +155,10 @@ final class AppDatabaseUpdater: AppDatabaseUpdaterProtocol {
     /// Starts an update for a specific server in the background.
     /// This method returns immediately and does not block the caller.
     /// - Parameter server: The specific server to update.
+    /// - Parameter forceUpdate: Forces update regardless of other conditions
     /// - Server updates are queued and processed sequentially, one at a time.
     /// - Applies per-server throttling with exponential backoff on failures.
-    func update(server: Server) {
+    func update(server: Server, forceUpdate: Bool) {
         // Explicitly detach from the calling context to ensure we don't block the main thread
         // Returns immediately while work continues in the background
         Task.detached(priority: .userInitiated) { [weak self] in
@@ -169,7 +170,7 @@ final class AppDatabaseUpdater: AppDatabaseUpdaterProtocol {
             await taskCoordinator.enqueueUpdate(serverId: serverId) { [weak self] in
                 guard let self else { return }
 
-                Current.Log.verbose("Updating database for server \(server.info.name)")
+                Current.Log.verbose("Updating database for server \(server.info.name)\(forceUpdate ? " (forced)" : "")")
 
                 // Show toast indicating update has started
                 await showUpdateToast(for: server)
@@ -185,7 +186,7 @@ final class AppDatabaseUpdater: AppDatabaseUpdaterProtocol {
                         }
                     }
 
-                    await performSingleServerUpdate(server: server)
+                    await performSingleServerUpdate(server: server, forceUpdate: forceUpdate)
                 }
 
                 // Store the task for this server
@@ -197,10 +198,15 @@ final class AppDatabaseUpdater: AppDatabaseUpdaterProtocol {
     }
 
     /// Determines if a specific server should be updated based on connection and throttle rules.
-    private func shouldUpdateServer(_ server: Server) -> Bool {
+    private func shouldUpdateServer(_ server: Server, forceUpdate: Bool) -> Bool {
         guard server.info.connection.activeURL() != nil else { return false }
         if isUpdateCancelled() { return false }
 
+        // Skip throttle checks if forceUpdate is true
+        if forceUpdate {
+            return true
+        }
+
         // Per-server throttle with exponential backoff
         if let last = perServerLastUpdate[server.identifier.rawValue] {
             let failures = consecutiveFailuresByServer[server.identifier.rawValue] ?? 0
@@ -212,9 +218,9 @@ final class AppDatabaseUpdater: AppDatabaseUpdaterProtocol {
     }
 
     /// Performs an update for a single specific server.
-    private func performSingleServerUpdate(server: Server) async {
+    private func performSingleServerUpdate(server: Server, forceUpdate: Bool) async {
         guard !isUpdateCancelled() else { return }
-        guard shouldUpdateServer(server) else {
+        guard shouldUpdateServer(server, forceUpdate: forceUpdate) else {
             Current.Log.verbose("Skipping update for server \(server.info.name) - throttled")
             return
         }

Sources/Shared/Resources/Swiftgen/Strings.swift

@@ -2540,6 +2540,8 @@ public enum L10n {
       public static var localPushDescription: String { return L10n.tr("Localizable", "settings.connection_section.local_push_description") }
       /// Logged in as
       public static var loggedInAs: String { return L10n.tr("Localizable", "settings.connection_section.logged_in_as") }
+      /// Update server information
+      public static var refreshServer: String { return L10n.tr("Localizable", "settings.connection_section.refresh_server") }
       /// Servers
       public static var servers: String { return L10n.tr("Localizable", "settings.connection_section.servers") }
       /// Reorder to define default server