Add config flow to Duck DNS integration (home-assistant#147693)

Co-authored-by: Franck Nijhof <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 3 people

CODEOWNERS

@@ -10,6 +10,7 @@
 from aiohttp import ClientSession
 import voluptuous as vol
 
+from homeassistant.config_entries import SOURCE_IMPORT, ConfigEntry
 from homeassistant.const import CONF_ACCESS_TOKEN, CONF_DOMAIN
 from homeassistant.core import (
     CALLBACK_TYPE,
@@ -18,21 +19,31 @@
     ServiceCall,
     callback,
 )
+from homeassistant.exceptions import ServiceValidationError
 from homeassistant.helpers import config_validation as cv
 from homeassistant.helpers.aiohttp_client import async_get_clientsession
 from homeassistant.helpers.event import async_call_later
+from homeassistant.helpers.selector import ConfigEntrySelector
 from homeassistant.helpers.typing import ConfigType
 from homeassistant.loader import bind_hass
 from homeassistant.util import dt as dt_util
 
+from .const import ATTR_CONFIG_ENTRY
+
 _LOGGER = logging.getLogger(__name__)
 
 ATTR_TXT = "txt"
 
 DOMAIN = "duckdns"
 
 INTERVAL = timedelta(minutes=5)
-
+BACKOFF_INTERVALS = (
+    INTERVAL,
+    timedelta(minutes=1),
+    timedelta(minutes=5),
+    timedelta(minutes=15),
+    timedelta(minutes=30),
+)
 SERVICE_SET_TXT = "set_txt"
 
 UPDATE_URL = "https://www.duckdns.org/update"
@@ -49,36 +60,109 @@
     extra=vol.ALLOW_EXTRA,
 )
 
-SERVICE_TXT_SCHEMA = vol.Schema({vol.Required(ATTR_TXT): vol.Any(None, cv.string)})
+SERVICE_TXT_SCHEMA = vol.Schema(
+    {
+        vol.Optional(ATTR_CONFIG_ENTRY): ConfigEntrySelector(
+            {
+                "integration": DOMAIN,
+            }
+        ),
+        vol.Optional(ATTR_TXT): vol.Any(None, cv.string),
+    }
+)
+
+type DuckDnsConfigEntry = ConfigEntry
 
 
 async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
     """Initialize the DuckDNS component."""
-    domain: str = config[DOMAIN][CONF_DOMAIN]
-    token: str = config[DOMAIN][CONF_ACCESS_TOKEN]
+
+    hass.services.async_register(
+        DOMAIN,
+        SERVICE_SET_TXT,
+        update_domain_service,
+        schema=SERVICE_TXT_SCHEMA,
+    )
+
+    if DOMAIN not in config:
+        return True
+
+    hass.async_create_task(
+        hass.config_entries.flow.async_init(
+            DOMAIN, context={"source": SOURCE_IMPORT}, data=config[DOMAIN]
+        )
+    )
+
+    return True
+
+
+async def async_setup_entry(hass: HomeAssistant, entry: DuckDnsConfigEntry) -> bool:
+    """Set up Duck DNS from a config entry."""
+
     session = async_get_clientsession(hass)
 
     async def update_domain_interval(_now: datetime) -> bool:
         """Update the DuckDNS entry."""
-        return await _update_duckdns(session, domain, token)
-
-    intervals = (
-        INTERVAL,
-        timedelta(minutes=1),
-        timedelta(minutes=5),
-        timedelta(minutes=15),
-        timedelta(minutes=30),
+        return await _update_duckdns(
+            session,
+            entry.data[CONF_DOMAIN],
+            entry.data[CONF_ACCESS_TOKEN],
+        )
+
+    entry.async_on_unload(
+        async_track_time_interval_backoff(
+            hass, update_domain_interval, BACKOFF_INTERVALS
+        )
     )
-    async_track_time_interval_backoff(hass, update_domain_interval, intervals)
 
-    async def update_domain_service(call: ServiceCall) -> None:
-        """Update the DuckDNS entry."""
-        await _update_duckdns(session, domain, token, txt=call.data[ATTR_TXT])
+    return True
 
-    hass.services.async_register(
-        DOMAIN, SERVICE_SET_TXT, update_domain_service, schema=SERVICE_TXT_SCHEMA
+
+def get_config_entry(
+    hass: HomeAssistant, entry_id: str | None = None
+) -> DuckDnsConfigEntry:
+    """Return config entry or raise if not found or not loaded."""
+
+    if entry_id is None:
+        if not (config_entries := hass.config_entries.async_entries(DOMAIN)):
+            raise ServiceValidationError(
+                translation_domain=DOMAIN,
+                translation_key="entry_not_found",
+            )
+
+        if len(config_entries) != 1:
+            raise ServiceValidationError(
+                translation_domain=DOMAIN,
+                translation_key="entry_not_selected",
+            )
+        return config_entries[0]
+
+    if not (entry := hass.config_entries.async_get_entry(entry_id)):
+        raise ServiceValidationError(
+            translation_domain=DOMAIN,
+            translation_key="entry_not_found",
+        )
+
+    return entry
+
+
+async def update_domain_service(call: ServiceCall) -> None:
+    """Update the DuckDNS entry."""
+
+    entry = get_config_entry(call.hass, call.data.get(ATTR_CONFIG_ENTRY))
+
+    session = async_get_clientsession(call.hass)
+
+    await _update_duckdns(
+        session,
+        entry.data[CONF_DOMAIN],
+        entry.data[CONF_ACCESS_TOKEN],
+        txt=call.data.get(ATTR_TXT),
     )
 
+
+async def async_unload_entry(hass: HomeAssistant, entry: DuckDnsConfigEntry) -> bool:
+    """Unload a config entry."""
     return True
 
 

homeassistant/components/duckdns/__init__.py

@@ -0,0 +1,81 @@
+"""Config flow for the Duck DNS integration."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import voluptuous as vol
+
+from homeassistant.config_entries import ConfigFlow, ConfigFlowResult
+from homeassistant.const import CONF_ACCESS_TOKEN, CONF_DOMAIN
+from homeassistant.helpers.aiohttp_client import async_get_clientsession
+from homeassistant.helpers.selector import (
+    TextSelector,
+    TextSelectorConfig,
+    TextSelectorType,
+)
+
+from . import _update_duckdns
+from .const import DOMAIN
+from .issue import deprecate_yaml_issue
+
+_LOGGER = logging.getLogger(__name__)
+
+STEP_USER_DATA_SCHEMA = vol.Schema(
+    {
+        vol.Required(CONF_DOMAIN): TextSelector(
+            TextSelectorConfig(type=TextSelectorType.TEXT, suffix=".duckdns.org")
+        ),
+        vol.Required(CONF_ACCESS_TOKEN): str,
+    }
+)
+
+
+class DuckDnsConfigFlow(ConfigFlow, domain=DOMAIN):
+    """Handle a config flow for Duck DNS."""
+
+    async def async_step_user(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        """Handle the initial step."""
+        errors: dict[str, str] = {}
+        if user_input is not None:
+            self._async_abort_entries_match({CONF_DOMAIN: user_input[CONF_DOMAIN]})
+            session = async_get_clientsession(self.hass)
+            try:
+                if not await _update_duckdns(
+                    session,
+                    user_input[CONF_DOMAIN],
+                    user_input[CONF_ACCESS_TOKEN],
+                ):
+                    errors["base"] = "update_failed"
+            except Exception:
+                _LOGGER.exception("Unexpected exception")
+                errors["base"] = "unknown"
+
+            if not errors:
+                return self.async_create_entry(
+                    title=f"{user_input[CONF_DOMAIN]}.duckdns.org", data=user_input
+                )
+
+        return self.async_show_form(
+            step_id="user",
+            data_schema=self.add_suggested_values_to_schema(
+                data_schema=STEP_USER_DATA_SCHEMA, suggested_values=user_input
+            ),
+            errors=errors,
+            description_placeholders={"url": "https://www.duckdns.org/"},
+        )
+
+    async def async_step_import(self, import_info: dict[str, Any]) -> ConfigFlowResult:
+        """Import config from yaml."""
+
+        self._async_abort_entries_match({CONF_DOMAIN: import_info[CONF_DOMAIN]})
+        result = await self.async_step_user(import_info)
+        if errors := result.get("errors"):
+            deprecate_yaml_issue(self.hass, import_success=False)
+            return self.async_abort(reason=errors["base"])
+
+        deprecate_yaml_issue(self.hass, import_success=True)
+        return result

homeassistant/components/duckdns/config_flow.py

@@ -0,0 +1,7 @@
+"""Constants for the Duck DNS integration."""
+
+from typing import Final
+
+DOMAIN = "duckdns"
+
+ATTR_CONFIG_ENTRY: Final = "config_entry_id"

homeassistant/components/duckdns/const.py

@@ -0,0 +1,40 @@
+"""Issues for Duck DNS integration."""
+
+from homeassistant.core import DOMAIN as HOMEASSISTANT_DOMAIN, HomeAssistant, callback
+from homeassistant.helpers.issue_registry import IssueSeverity, async_create_issue
+
+from .const import DOMAIN
+
+
+@callback
+def deprecate_yaml_issue(hass: HomeAssistant, *, import_success: bool) -> None:
+    """Deprecate yaml issue."""
+    if import_success:
+        async_create_issue(
+            hass,
+            HOMEASSISTANT_DOMAIN,
+            f"deprecated_yaml_{DOMAIN}",
+            is_fixable=False,
+            issue_domain=DOMAIN,
+            breaks_in_ha_version="2026.6.0",
+            severity=IssueSeverity.WARNING,
+            translation_key="deprecated_yaml",
+            translation_placeholders={
+                "domain": DOMAIN,
+                "integration_title": "Duck DNS",
+            },
+        )
+    else:
+        async_create_issue(
+            hass,
+            DOMAIN,
+            "deprecated_yaml_import_issue_error",
+            breaks_in_ha_version="2026.6.0",
+            is_fixable=False,
+            issue_domain=DOMAIN,
+            severity=IssueSeverity.WARNING,
+            translation_key="deprecated_yaml_import_issue_error",
+            translation_placeholders={
+                "url": "/config/integrations/dashboard/add?domain=duckdns"
+            },
+        )

homeassistant/components/duckdns/issue.py

@@ -1,8 +1,8 @@
 {
   "domain": "duckdns",
   "name": "Duck DNS",
-  "codeowners": [],
+  "codeowners": ["@tr4nt0r"],
+  "config_flow": true,
   "documentation": "https://www.home-assistant.io/integrations/duckdns",
-  "iot_class": "cloud_polling",
-  "quality_scale": "legacy"
+  "iot_class": "cloud_polling"
 }

homeassistant/components/duckdns/manifest.json

@@ -1,7 +1,10 @@
 set_txt:
   fields:
+    config_entry_id:
+      selector:
+        config_entry:
+          integration: duckdns
     txt:
-      required: true
       example: "This domain name is reserved for use in documentation"
       selector:
         text:

homeassistant/components/duckdns/services.yaml

@@ -1,8 +1,48 @@
 {
+  "config": {
+    "abort": {
+      "already_configured": "[%key:common::config_flow::abort::already_configured_device%]"
+    },
+    "error": {
+      "unknown": "[%key:common::config_flow::error::unknown%]",
+      "update_failed": "Updating DuckDNS failed"
+    },
+    "step": {
+      "user": {
+        "data": {
+          "access_token": "Token",
+          "domain": "Subdomain"
+        },
+        "data_description": {
+          "access_token": "Your Duck DNS account token",
+          "domain": "The Duck DNS subdomain to update"
+        },
+        "description": "Enter your Duck DNS subdomain and token below to configure dynamic DNS updates. You can find your token on the [Duck DNS]({url}) homepage after logging into your account."
+      }
+    }
+  },
+  "exceptions": {
+    "entry_not_found": {
+      "message": "Duck DNS integration entry not found"
+    },
+    "entry_not_selected": {
+      "message": "Duck DNS integration entry not selected"
+    }
+  },
+  "issues": {
+    "deprecated_yaml_import_issue_error": {
+      "description": "Configuring Duck DNS using YAML is being removed but there was an error when trying to import the YAML configuration.\n\nEnsure the YAML configuration is correct and restart Home Assistant to try again or remove the Duck DNS YAML configuration from your `configuration.yaml` file and continue to [set up the integration]({url}) manually.",
+      "title": "The Duck DNS YAML configuration import failed"
+    }
+  },
   "services": {
     "set_txt": {
       "description": "Sets the TXT record of your DuckDNS subdomain.",
       "fields": {
+        "config_entry_id": {
+          "description": "The Duck DNS integration ID.",
+          "name": "Integration ID"
+        },
         "txt": {
           "description": "Payload for the TXT record.",
           "name": "TXT"

homeassistant/components/duckdns/strings.json

@@ -1467,7 +1467,7 @@
     "duckdns": {
       "name": "Duck DNS",
       "integration_type": "hub",
-      "config_flow": false,
+      "config_flow": true,
       "iot_class": "cloud_polling"
     },
     "duke_energy": {