Add azure_storage as backup agent (#134085)

Co-authored-by: Martin Hjelmare <[email protected]>

Author: zweckj

Diff for: .strict-typing

@@ -103,6 +103,7 @@ homeassistant.components.auth.*
 homeassistant.components.automation.*
 homeassistant.components.awair.*
 homeassistant.components.axis.*
+homeassistant.components.azure_storage.*
 homeassistant.components.backup.*
 homeassistant.components.baf.*
 homeassistant.components.bang_olufsen.*

Diff for: CODEOWNERS

@@ -6,6 +6,7 @@
     "azure_devops",
     "azure_event_hub",
     "azure_service_bus",
+    "azure_storage",
     "microsoft_face_detect",
     "microsoft_face_identify",
     "microsoft_face",

Diff for: homeassistant/brands/microsoft.json

@@ -0,0 +1,82 @@
+"""The Azure Storage integration."""
+
+from aiohttp import ClientTimeout
+from azure.core.exceptions import (
+    ClientAuthenticationError,
+    HttpResponseError,
+    ResourceNotFoundError,
+)
+from azure.core.pipeline.transport._aiohttp import (
+    AioHttpTransport,
+)  # need to import from private file, as it is not properly imported in the init
+from azure.storage.blob.aio import ContainerClient
+
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.core import HomeAssistant
+from homeassistant.exceptions import ConfigEntryError, ConfigEntryNotReady
+from homeassistant.helpers.aiohttp_client import async_create_clientsession
+
+from .const import (
+    CONF_ACCOUNT_NAME,
+    CONF_CONTAINER_NAME,
+    CONF_STORAGE_ACCOUNT_KEY,
+    DATA_BACKUP_AGENT_LISTENERS,
+    DOMAIN,
+)
+
+type AzureStorageConfigEntry = ConfigEntry[ContainerClient]
+
+
+async def async_setup_entry(
+    hass: HomeAssistant, entry: AzureStorageConfigEntry
+) -> bool:
+    """Set up Azure Storage integration."""
+    # set increase aiohttp timeout for long running operations (up/download)
+    session = async_create_clientsession(
+        hass, timeout=ClientTimeout(connect=10, total=12 * 60 * 60)
+    )
+    container_client = ContainerClient(
+        account_url=f"https://{entry.data[CONF_ACCOUNT_NAME]}.blob.core.windows.net/",
+        container_name=entry.data[CONF_CONTAINER_NAME],
+        credential=entry.data[CONF_STORAGE_ACCOUNT_KEY],
+        transport=AioHttpTransport(session=session),
+    )
+
+    try:
+        if not await container_client.exists():
+            await container_client.create_container()
+    except ResourceNotFoundError as err:
+        raise ConfigEntryError(
+            translation_domain=DOMAIN,
+            translation_key="account_not_found",
+            translation_placeholders={CONF_ACCOUNT_NAME: entry.data[CONF_ACCOUNT_NAME]},
+        ) from err
+    except ClientAuthenticationError as err:
+        raise ConfigEntryError(
+            translation_domain=DOMAIN,
+            translation_key="invalid_auth",
+            translation_placeholders={CONF_ACCOUNT_NAME: entry.data[CONF_ACCOUNT_NAME]},
+        ) from err
+    except HttpResponseError as err:
+        raise ConfigEntryNotReady(
+            translation_domain=DOMAIN,
+            translation_key="cannot_connect",
+            translation_placeholders={CONF_ACCOUNT_NAME: entry.data[CONF_ACCOUNT_NAME]},
+        ) from err
+
+    entry.runtime_data = container_client
+
+    def _async_notify_backup_listeners() -> None:
+        for listener in hass.data.get(DATA_BACKUP_AGENT_LISTENERS, []):
+            listener()
+
+    entry.async_on_unload(entry.async_on_state_change(_async_notify_backup_listeners))
+
+    return True
+
+
+async def async_unload_entry(
+    hass: HomeAssistant, entry: AzureStorageConfigEntry
+) -> bool:
+    """Unload an Azure Storage config entry."""
+    return True

Diff for: homeassistant/components/azure_storage/__init__.py

@@ -0,0 +1,182 @@
+"""Support for Azure Storage backup."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable, Coroutine
+from functools import wraps
+import json
+import logging
+from typing import Any, Concatenate
+
+from azure.core.exceptions import HttpResponseError
+from azure.storage.blob import BlobProperties
+
+from homeassistant.components.backup import (
+    AgentBackup,
+    BackupAgent,
+    BackupAgentError,
+    BackupNotFound,
+    suggested_filename,
+)
+from homeassistant.core import HomeAssistant, callback
+
+from . import AzureStorageConfigEntry
+from .const import DATA_BACKUP_AGENT_LISTENERS, DOMAIN
+
+_LOGGER = logging.getLogger(__name__)
+METADATA_VERSION = "1"
+
+
+async def async_get_backup_agents(
+    hass: HomeAssistant,
+) -> list[BackupAgent]:
+    """Return a list of backup agents."""
+    entries: list[AzureStorageConfigEntry] = hass.config_entries.async_loaded_entries(
+        DOMAIN
+    )
+    return [AzureStorageBackupAgent(hass, entry) for entry in entries]
+
+
+@callback
+def async_register_backup_agents_listener(
+    hass: HomeAssistant,
+    *,
+    listener: Callable[[], None],
+    **kwargs: Any,
+) -> Callable[[], None]:
+    """Register a listener to be called when agents are added or removed."""
+    hass.data.setdefault(DATA_BACKUP_AGENT_LISTENERS, []).append(listener)
+
+    @callback
+    def remove_listener() -> None:
+        """Remove the listener."""
+        hass.data[DATA_BACKUP_AGENT_LISTENERS].remove(listener)
+        if not hass.data[DATA_BACKUP_AGENT_LISTENERS]:
+            hass.data.pop(DATA_BACKUP_AGENT_LISTENERS)
+
+    return remove_listener
+
+
+def handle_backup_errors[_R, **P](
+    func: Callable[Concatenate[AzureStorageBackupAgent, P], Coroutine[Any, Any, _R]],
+) -> Callable[Concatenate[AzureStorageBackupAgent, P], Coroutine[Any, Any, _R]]:
+    """Handle backup errors."""
+
+    @wraps(func)
+    async def wrapper(
+        self: AzureStorageBackupAgent, *args: P.args, **kwargs: P.kwargs
+    ) -> _R:
+        try:
+            return await func(self, *args, **kwargs)
+        except HttpResponseError as err:
+            _LOGGER.debug(
+                "Error during backup in %s: Status %s, message %s",
+                func.__name__,
+                err.status_code,
+                err.message,
+                exc_info=True,
+            )
+            raise BackupAgentError(
+                f"Error during backup operation in {func.__name__}:"
+                f" Status {err.status_code}, message: {err.message}"
+            ) from err
+
+    return wrapper
+
+
+class AzureStorageBackupAgent(BackupAgent):
+    """Azure storage backup agent."""
+
+    domain = DOMAIN
+
+    def __init__(self, hass: HomeAssistant, entry: AzureStorageConfigEntry) -> None:
+        """Initialize the Azure storage backup agent."""
+        super().__init__()
+        self._client = entry.runtime_data
+        self.name = entry.title
+        self.unique_id = entry.entry_id
+
+    @handle_backup_errors
+    async def async_download_backup(
+        self,
+        backup_id: str,
+        **kwargs: Any,
+    ) -> AsyncIterator[bytes]:
+        """Download a backup file."""
+        blob = await self._find_blob_by_backup_id(backup_id)
+        if blob is None:
+            raise BackupNotFound(f"Backup {backup_id} not found")
+        download_stream = await self._client.download_blob(blob.name)
+        return download_stream.chunks()
+
+    @handle_backup_errors
+    async def async_upload_backup(
+        self,
+        *,
+        open_stream: Callable[[], Coroutine[Any, Any, AsyncIterator[bytes]]],
+        backup: AgentBackup,
+        **kwargs: Any,
+    ) -> None:
+        """Upload a backup."""
+
+        metadata = {
+            "metadata_version": METADATA_VERSION,
+            "backup_id": backup.backup_id,
+            "backup_metadata": json.dumps(backup.as_dict()),
+        }
+
+        await self._client.upload_blob(
+            name=suggested_filename(backup),
+            metadata=metadata,
+            data=await open_stream(),
+            length=backup.size,
+        )
+
+    @handle_backup_errors
+    async def async_delete_backup(
+        self,
+        backup_id: str,
+        **kwargs: Any,
+    ) -> None:
+        """Delete a backup file."""
+        blob = await self._find_blob_by_backup_id(backup_id)
+        if blob is None:
+            return
+        await self._client.delete_blob(blob.name)
+
+    @handle_backup_errors
+    async def async_list_backups(self, **kwargs: Any) -> list[AgentBackup]:
+        """List backups."""
+        backups: list[AgentBackup] = []
+        async for blob in self._client.list_blobs(include="metadata"):
+            metadata = blob.metadata
+
+            if metadata.get("metadata_version") == METADATA_VERSION:
+                backups.append(
+                    AgentBackup.from_dict(json.loads(metadata["backup_metadata"]))
+                )
+
+        return backups
+
+    @handle_backup_errors
+    async def async_get_backup(
+        self,
+        backup_id: str,
+        **kwargs: Any,
+    ) -> AgentBackup | None:
+        """Return a backup."""
+        blob = await self._find_blob_by_backup_id(backup_id)
+        if blob is None:
+            return None
+
+        return AgentBackup.from_dict(json.loads(blob.metadata["backup_metadata"]))
+
+    async def _find_blob_by_backup_id(self, backup_id: str) -> BlobProperties | None:
+        """Find a blob by backup id."""
+        async for blob in self._client.list_blobs(include="metadata"):
+            if (
+                backup_id == blob.metadata.get("backup_id", "")
+                and blob.metadata.get("metadata_version") == METADATA_VERSION
+            ):
+                return blob
+        return None

Diff for: homeassistant/components/azure_storage/backup.py

@@ -0,0 +1,72 @@
+"""Config flow for Azure Storage integration."""
+
+import logging
+from typing import Any
+
+from azure.core.exceptions import ClientAuthenticationError, ResourceNotFoundError
+from azure.core.pipeline.transport._aiohttp import (
+    AioHttpTransport,
+)  # need to import from private file, as it is not properly imported in the init
+from azure.storage.blob.aio import ContainerClient
+import voluptuous as vol
+
+from homeassistant.config_entries import ConfigFlow, ConfigFlowResult
+from homeassistant.helpers.aiohttp_client import async_get_clientsession
+
+from .const import (
+    CONF_ACCOUNT_NAME,
+    CONF_CONTAINER_NAME,
+    CONF_STORAGE_ACCOUNT_KEY,
+    DOMAIN,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class AzureStorageConfigFlow(ConfigFlow, domain=DOMAIN):
+    """Handle a config flow for azure storage."""
+
+    async def async_step_user(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        """User step for Azure Storage."""
+
+        errors: dict[str, str] = {}
+
+        if user_input is not None:
+            self._async_abort_entries_match(
+                {CONF_ACCOUNT_NAME: user_input[CONF_ACCOUNT_NAME]}
+            )
+            container_client = ContainerClient(
+                account_url=f"https://{user_input[CONF_ACCOUNT_NAME]}.blob.core.windows.net/",
+                container_name=user_input[CONF_CONTAINER_NAME],
+                credential=user_input[CONF_STORAGE_ACCOUNT_KEY],
+                transport=AioHttpTransport(session=async_get_clientsession(self.hass)),
+            )
+            try:
+                await container_client.exists()
+            except ResourceNotFoundError:
+                errors["base"] = "cannot_connect"
+            except ClientAuthenticationError:
+                errors[CONF_STORAGE_ACCOUNT_KEY] = "invalid_auth"
+            except Exception:
+                _LOGGER.exception("Unknown exception occurred")
+                errors["base"] = "unknown"
+            if not errors:
+                return self.async_create_entry(
+                    title=f"{user_input[CONF_ACCOUNT_NAME]}/{user_input[CONF_CONTAINER_NAME]}",
+                    data=user_input,
+                )
+
+        return self.async_show_form(
+            data_schema=vol.Schema(
+                {
+                    vol.Required(CONF_ACCOUNT_NAME): str,
+                    vol.Required(
+                        CONF_CONTAINER_NAME, default="home-assistant-backups"
+                    ): str,
+                    vol.Required(CONF_STORAGE_ACCOUNT_KEY): str,
+                }
+            ),
+            errors=errors,
+        )

Diff for: homeassistant/components/azure_storage/config_flow.py

@@ -0,0 +1,16 @@
+"""Constants for the Azure Storage integration."""
+
+from collections.abc import Callable
+from typing import Final
+
+from homeassistant.util.hass_dict import HassKey
+
+DOMAIN: Final = "azure_storage"
+
+CONF_STORAGE_ACCOUNT_KEY: Final = "storage_account_key"
+CONF_ACCOUNT_NAME: Final = "account_name"
+CONF_CONTAINER_NAME: Final = "container_name"
+
+DATA_BACKUP_AGENT_LISTENERS: HassKey[list[Callable[[], None]]] = HassKey(
+    f"{DOMAIN}.backup_agent_listeners"
+)

Diff for: homeassistant/components/azure_storage/const.py

@@ -0,0 +1,12 @@
+{
+  "domain": "azure_storage",
+  "name": "Azure Storage",
+  "codeowners": ["@zweckj"],
+  "config_flow": true,
+  "documentation": "https://www.home-assistant.io/integrations/azure_storage",
+  "integration_type": "service",
+  "iot_class": "cloud_polling",
+  "loggers": ["azure-storage-blob"],
+  "quality_scale": "bronze",
+  "requirements": ["azure-storage-blob==12.24.0"]
+}