Add entity-change push subscriptions to mobile_app - #174943
Add entity-change push subscriptions to mobile_app#174943hariharanjagan wants to merge 31 commits into
Conversation
![home-assistant[bot]](https://avatars.githubusercontent.com/in/97978?s=60&v=4){kind=small}
There was a problem hiding this comment.
It seems you haven't yet signed a CLA. Please do so here.
Once you do that we will be able to review and accept this pull request.
Thanks!
home-assistant
Bot
added
cla-needed
core
integration: mobile_app
new-feature
new-integration
labels
|
Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍 |
|
Hey there @home-assistant/core, mind taking a look at this pull request as it has been labeled with an integration ( Code owner commandsCode owners of
|
There was a problem hiding this comment.
Pull request overview
This PR adds a platform-agnostic push-subscription mechanism to the mobile_app integration. A companion app registers a push token plus a set of entity_ids via two new webhook commands; Core then tracks those entities' state changes and sends a debounced, best-effort silent push to the app's existing push URL. The first consumer is iOS WidgetKit timeline refresh, but the contract is deliberately generic. The implementation closely mirrors the existing live_activity subpackage for persistence/lifecycle, bumping storage minor version 2 → 3 with a seeding migration.
Changes:
- New
push_subscription/subpackage: webhook handlers (register/remove), storage + per-subscription trailing-edge debounce + listener teardown/restore, and the outgoing silent-push sender. - New constants and storage version bump, plus persistence of the subscriptions mapping in
savable_state(). - Lifecycle wiring in
__init__.py: seedhass.datakeys, restore on entry setup, tear down on unload, drop on removal, and a minor-3 migration step.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
push_subscription/webhook.py |
Adds register_push_subscription / remove_push_subscription webhook commands with schema validation. |
push_subscription/store.py |
Stores subscriptions, arms/cancels state-change listeners, and implements per-subscription debounce. |
push_subscription/notify.py |
Builds and posts the minimal silent push payload to the device's push URL (fire-and-forget). |
push_subscription/__init__.py |
Package init; imports webhook to register commands and re-exports lifecycle helpers. |
helpers.py |
Persists the subscriptions mapping in savable_state(). |
const.py |
New payload/data keys, debounce window constant, and STORAGE_VERSION_MINOR 2 → 3. |
__init__.py |
Seeds new hass.data keys, restores/tears down/removes subscriptions across entry lifecycle, and adds the minor-3 migration. |
There was a problem hiding this comment.
It seems you haven't yet signed a CLA. Please do so here.
Once you do that we will be able to review and accept this pull request.
Thanks!
home-assistant
Bot
added
cla-recheck
cla-signed
and removed
cla-recheck
cla-needed
labels
|
I haven't looked into the PR, but reading the description I was thinking, wouldn’t it make more sense for 1 entity to have N push tokens instead? Using the iOS companion app as an example, this would allow to update a widget and a control Center control at the same time in case both use the same entity |
| from homeassistant.components.mobile_app.push_subscription.notify import ( | ||
| _send_subscription_push, | ||
| ) |
Extract the inline 50 in the register schema into PUSH_SUBSCRIPTION_MAX_ENTITY_IDS so it sits with the other two subscription limits and is self-documenting.
| # Patch target for the inner coroutine that performs the HTTP POST, letting the | ||
| # debounce/scheduling logic run under test while the network call is stubbed. | ||
| SEND_PUSH = ( | ||
| "homeassistant.components.mobile_app.push_subscription" | ||
| ".notify._send_subscription_push" | ||
| ) | ||
| # async_get_clientsession as looked up inside notify.py - patched in the two | ||
| # direct _send_subscription_push tests so the POST never touches the network. | ||
| GET_SESSION = ( | ||
| "homeassistant.components.mobile_app.push_subscription" | ||
| ".notify.async_get_clientsession" | ||
| ) |
| vol.Required(PUSH_SUBSCRIPTION_ENTITY_IDS): vol.All( | ||
| cv.ensure_list, | ||
| [cv.entity_id], | ||
| vol.Length(min=1, max=PUSH_SUBSCRIPTION_MAX_ENTITY_IDS), | ||
| _unique_entity_ids, | ||
| ), |
| A push subscription maps a push token to a set of entity_ids. The integration | ||
| owns the mapping and the state tracking; it has no knowledge of what the app | ||
| does with the resulting push. |
There was a problem hiding this comment.
One of my initial comments was to have 1 entity_id link to N push tokens, so if that entity ID updates we can update multiple parts of the app at once, example: Widgets, Watch Complications, Control Center Controls
|
|
||
| # Trailing-edge debounce window: a burst of state changes within this many | ||
| # seconds collapses to a single push. | ||
| PUSH_SUBSCRIPTION_DEBOUNCE_SECONDS = 5.0 |
There was a problem hiding this comment.
Should debounce be defined by the client? Let's say that one client can handle more frequent updates than other client, shouldn't them be able to control that?
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.
Suppressed comments (1)
homeassistant/components/mobile_app/push_subscription/store.py:115
- Refresh subscription trackers whenever
update_registrationchangesapp_data. A subscription stored whilepush_urlis absent remains listenerless after that webhook later adds the URL, while removing the URL leaves its existing listener active because the update handler only updates the entry and reloads notify; rerun tracker setup/teardown after the registration update.
# Only arm a listener for registrations that can send a cloud push; others
# would schedule a debounce timer on every state change that never sends.
entry = hass.data[DOMAIN][DATA_CONFIG_ENTRIES].get(webhook_id)
if entry is None or ATTR_PUSH_URL not in entry.data.get(ATTR_APP_DATA, {}):
return
| if not hass.is_running: | ||
| return | ||
| _async_schedule_push(hass, webhook_id, sub_id) |
Breaking change
Proposed change
Adds an entity-driven push subscription mechanism to the mobile_app integration. A companion app registers a push token together with a set of entity_ids it wants to observe, the integration then tracks state changes on those entities and POSTs a minimal payload to the app's registered push URL whenever one of them changes.
Two webhook commands are exposed on the existing mobile_app webhook: one to register a subscription subscription_id, push_token, entity_ids, optional target and one to remove it.
Registration is idempotent on subscription_id, so re-registering with a rotated token or a changed entity set overwrites the previous state in place rather than creating a duplicate.
Bounds:
entity_ids is validated and capped at 1–50 per subscription duplicate entity_ids are dropped).
Subscriptions are capped at 50 per device, evicting the oldest first. Together these bound how many state listeners a single device can arm. State-change delivery is debounced per subscription (5s trailing edge), so a burst of changes collapses into a single push.
Type of change
Additional information
Checklist
ruff format homeassistant tests)If user exposed functionality or configuration variables are added/changed:
Documentation added/updated for www.home-assistant.io
Link to developer documentation pull request: Document push subscription webhook commands developers.home-assistant#3230
If the code communicates with devices, web services, or third-party tools:
Updated and included derived files by running:
python3 -m script.hassfest.requirements_all.txt.Updated by running
python3 -m script.gen_requirements_all.To help with the load of incoming pull requests:
Related Pull Requests
iOS - home-assistant/iOS#4939
FCM - home-assistant/mobile-apps-fcm-push#337