Add documentation for sync agents #2434
Conversation
📝 WalkthroughWalkthroughThe changes introduce a new documentation file and updates to the existing backup platform documentation in Home Assistant Core 2025.12. The new file details the "Backup sync agents" feature, explaining how integrations can utilize sync agents for backing up and restoring user data to external services. The backup platform documentation is enhanced with new sections on pre/post backup hooks and sync agents, including details on the implementation of a new class and methods for managing backups. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant HomeAssistant
participant BackupSyncAgent
User->>HomeAssistant: Request backup
HomeAssistant->>BackupSyncAgent: async_upload_backup(path, metadata)
BackupSyncAgent-->>HomeAssistant: Confirm upload
HomeAssistant-->>User: Backup completed
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Outside diff range and nitpick comments (4)
docs/core/platform/backup.md (4)
5-5: Fix grammatical issues in the introduction.Consider revising for better clarity and correct grammar:
-The backup platform consists of two parts; [Pre/Post backup hooks](#prepost-backup-hooks) and [Sync agents](#sync-agents). +The backup platform consists of two parts: [Pre/Post-backup hooks](#prepost-backup-hooks) and [Sync agents](#sync-agents).
9-9: Improve technical writing style.Consider using more formal language:
-When Home Assistant is creating a backup, there might be a need to pause certain operations in the integration, or dumping data so it can properly be restored. +When Home Assistant is creating a backup, there might be a need to pause certain operations in the integration or export data for proper restoration.🧰 Tools
🪛 LanguageTool
[uncategorized] ~9-~9: This verb may not be in the correct form. Consider using a different form for this context.
Context: ...rtain operations in the integration, or dumping data so it can properly be restored. T...(AI_EN_LECTOR_REPLACEMENT_VERB_FORM)
32-34: Fix grammatical issues in the sync agents introduction.Several grammar issues need to be addressed:
-Sync agents are used to dispatch a backup to a remote location. This is done by implementing the a `BackupSyncAgent` class. -To register your sync agent, you need to add a `async_get_backup_sync_agents` function to your integrations backup platform. +Sync agents are used to dispatch a backup to a remote location. This is done by implementing a `BackupSyncAgent` class. +To register your sync agent, you need to add an `async_get_backup_sync_agents` function to your integration's backup platform.🧰 Tools
🪛 LanguageTool
[grammar] ~32-~32: Two determiners in a row. Choose either “the” or “a”.
Context: ... location. This is done by implementing the aBackupSyncAgentclass. To register y...(DT_DT)
[uncategorized] ~34-~34: The grammatical number of this noun doesn’t look right. Consider replacing it.
Context: ...et_backup_sync_agents` function to your integrations backup platform. ```python async def a...(AI_EN_LECTOR_REPLACEMENT_NOUN_NUMBER)
43-45: Consider providing a more complete code example.The current example uses
...which might not be sufficient for developers to understand the implementation requirements. Consider showing at least one implemented method to demonstrate the expected pattern.Would you like me to provide a more complete example implementation?
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (2)
blog/2025-12-31-backup-sync-agents.md(1 hunks)docs/core/platform/backup.md(2 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
blog/2025-12-31-backup-sync-agents.md (6)
Pattern */**(html|markdown|md): - For instructional content in documentation, use a direct and authoritative tone. Avoid expressions of politeness such as 'may' or 'please', and ensure the goal of the instruction is fronted.
- Apply the Microsoft Style Guide to ensure documentation maintains clarity and conciseness.
- In step-by-step instructions, front the location phrase in the instructional sentence.
- In step-by-step instructions, front the 'goal' in the instructional sentence.
- In step-by-step instructions, if in doubt what to front, front the 'goal' before the location phrase in the instructional sentence.
- do not hyphenate terms like 'top-right' or 'bottom-left' with 'corner'
Pattern */**(html|markdown|md): - Use bold to mark UI strings.
- If "" are used to mark UI strings, replace them by bold.
Pattern */**(html|markdown|md): - Be brief in your replies and don't add fluff like "thank you for..." and "Please let me know if"
Pattern */**(html|markdown|md): - Use sentence-style capitalization also in headings.
Pattern */**(html|markdown|md): do not comment on HTML used for icons
Pattern */**(html|markdown|md): Avoid flagging inline HTML for embedding videos in future reviews for this repository.
🪛 LanguageTool
blog/2025-12-31-backup-sync-agents.md
[grammar] ~11-~11: It seems that the correct verb form here is “allow”.
Context: ...nd from external services. Sync agents allows integrations to store backups in a remo...
(AGREEMENT_SENT_START_2)
docs/core/platform/backup.md
[grammar] ~7-~7: It appears that hyphens are missing.
Context: ...s) and Sync agents. ## Pre/Post backup hooks When Home Assistant is creating ...
(PRE_AND_POST_NN)
[uncategorized] ~9-~9: This verb may not be in the correct form. Consider using a different form for this context.
Context: ...rtain operations in the integration, or dumping data so it can properly be restored. T...
(AI_EN_LECTOR_REPLACEMENT_VERB_FORM)
[grammar] ~32-~32: Two determiners in a row. Choose either “the” or “a”.
Context: ... location. This is done by implementing the a BackupSyncAgent class. To register y...
(DT_DT)
[uncategorized] ~34-~34: The grammatical number of this noun doesn’t look right. Consider replacing it.
Context: ...et_backup_sync_agents` function to your integrations backup platform. ```python async def a...
(AI_EN_LECTOR_REPLACEMENT_NOUN_NUMBER)
[uncategorized] ~55-~55: Possible missing preposition found.
Context: ... be synced. async_list_backups | List backups. When a user creates a backup, Home As...
(AI_HYDRA_LEO_MISSING_OF)
docs/core/platform/backup.md
Outdated
| The base class `BackupSyncAgent` has several methods that can needs to be implemented. | ||
|
|
||
| Method | Description | ||
| :--- | :--- | ||
| `async_download_backup` | Download a backup from the remote location. The `id` parameter is the ID of the synced backup that was returned in `async_list_backups`. The `path` parameter is the full file path to download the synced backup to. | ||
| `async_upload_backup` | Upload a backup. The `path` parameter is the full file path to the backup that should be synced. The `metadata` parameter contains metadata about the backup that should be synced. | ||
| `async_list_backups` | List backups. |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Fix grammar and enhance method descriptions.
The method descriptions section needs grammatical fixes and could benefit from more detailed information:
-The base class `BackupSyncAgent` has several methods that can needs to be implemented.
+The base class `BackupSyncAgent` has several methods that need to be implemented.Consider adding return type information and error handling expectations for each method in the table.
Here's a suggested enhancement for the method table:
| Method | Description | Return Type | Error Handling |
|---|---|---|---|
async_download_backup |
Downloads a backup from the remote location using the provided ID. | None |
Should raise BackupError on failure |
async_upload_backup |
Uploads a backup file with associated metadata to the remote location. | str (backup ID) |
Should raise BackupError on failure |
async_list_backups |
Retrieves a list of available backups from the remote location. | list[BackupInfo] |
Should raise BackupError on connection issues |
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| The base class `BackupSyncAgent` has several methods that can needs to be implemented. | |
| Method | Description | |
| :--- | :--- | |
| `async_download_backup` | Download a backup from the remote location. The `id` parameter is the ID of the synced backup that was returned in `async_list_backups`. The `path` parameter is the full file path to download the synced backup to. | |
| `async_upload_backup` | Upload a backup. The `path` parameter is the full file path to the backup that should be synced. The `metadata` parameter contains metadata about the backup that should be synced. | |
| `async_list_backups` | List backups. | |
| The base class `BackupSyncAgent` has several methods that need to be implemented. | |
| Method | Description | |
| :--- | :--- | |
| `async_download_backup` | Download a backup from the remote location. The `id` parameter is the ID of the synced backup that was returned in `async_list_backups`. The `path` parameter is the full file path to download the synced backup to. | |
| `async_upload_backup` | Upload a backup. The `path` parameter is the full file path to the backup that should be synced. The `metadata` parameter contains metadata about the backup that should be synced. | |
| `async_list_backups` | List backups. |
🧰 Tools
🪛 LanguageTool
[uncategorized] ~55-~55: Possible missing preposition found.
Context: ... be synced. async_list_backups | List backups. When a user creates a backup, Home As...
(AI_HYDRA_LEO_MISSING_OF)
Proposed change
Documentation and short blog for home-assistant/core#126122
Type of change
Additional information
Summary by CodeRabbit
New Features
Documentation