wled-screen-controller-mixed/contexts/auto-update-plan.md

Auto-Update Plan — Phase 1: Check & Notify

Created: 2026-03-25. Status: planned, not started.

Backend Architecture

Release Provider Abstraction

core/update/
    release_provider.py   — ABC: get_releases(), get_releases_page_url()
    gitea_provider.py     — Gitea REST API implementation
    version_check.py      — normalize_version(), is_newer() using packaging.version
    update_service.py     — Background asyncio task + state machine

ReleaseProvider interface — two methods:

• get_releases(limit) → list[ReleaseInfo] — fetch releases (newest first)
• get_releases_page_url() → str — link for "view on web"

GiteaReleaseProvider calls GET {base_url}/api/v1/repos/{repo}/releases. Swapping to GitHub later means implementing the same interface against api.github.com.

Data models:

@dataclass(frozen=True)
class AssetInfo:
    name: str          # "LedGrab-v0.3.0-win-x64.zip"
    size: int          # bytes
    download_url: str

@dataclass(frozen=True)
class ReleaseInfo:
    tag: str           # "v0.3.0"
    version: str       # "0.3.0"
    name: str          # "LedGrab v0.3.0"
    body: str          # release notes markdown
    prerelease: bool
    published_at: str  # ISO 8601
    assets: tuple[AssetInfo, ...]

Version Comparison

version_check.py — normalize Gitea tags to PEP 440:

• v0.3.0-alpha.1 → 0.3.0a1
• v0.3.0-beta.2 → 0.3.0b2
• v0.3.0-rc.3 → 0.3.0rc3

Uses packaging.version.Version for comparison.

Update Service

Follows the AutoBackupEngine pattern:

• Settings in Database.get_setting("auto_update")
• asyncio.Task for periodic checks
• 30s startup delay (avoid slowing boot)
• 60s debounce on manual checks

State machine (Phase 1): IDLE → CHECKING → UPDATE_AVAILABLE

No download/apply in Phase 1 — just detection and notification.

Settings: enabled (bool), check_interval_hours (float), channel ("stable" | "pre-release")

Persisted state: dismissed_version, last_check (survives restarts)

API Endpoints

Method	Path	Purpose
GET	/api/v1/system/update/status	Current state + available version
POST	/api/v1/system/update/check	Trigger immediate check
POST	/api/v1/system/update/dismiss	Dismiss notification for current version
GET	/api/v1/system/update/settings	Get settings
PUT	/api/v1/system/update/settings	Update settings

Wiring

• New get_update_service() in dependencies.py
• UpdateService created in main.py lifespan, start()/stop() alongside other engines
• Router registered in api/__init__.py
• WebSocket event: update_available fired via processor_manager.fire_event()

Frontend

Version badge highlight

The existing #server-version pill in the header gets a CSS class has-update when a newer version exists — changes the background to var(--warning-color) with a subtle pulse, making it clickable to open the update panel in settings.

Notification popup

On server:update_available WebSocket event (and on page load if status says has_update and not dismissed):

• A persistent dismissible banner slides in below the header (not the ephemeral 3s toast)
• Shows: "Version {x.y.z} is available" + [View Release Notes] + [Dismiss]
• Dismiss calls POST /dismiss and hides the bar for that version
• Stored in localStorage so it doesn't re-show after page refresh for dismissed versions

Settings tab: "Updates"

New 5th tab in the settings modal:

• Current version display
• "Check for updates" button + spinner
• Channel selector (stable / pre-release) via IconSelect
• Auto-check toggle + interval selector
• When update available: release name, notes preview, link to releases page

i18n keys

New update.* keys in en.json, ru.json, zh.json for all labels.

Files to Create

File	Purpose
core/update/__init__.py	Package init
core/update/release_provider.py	Abstract provider interface + data models
core/update/gitea_provider.py	Gitea API implementation
core/update/version_check.py	Semver normalization + comparison
core/update/update_service.py	Background service + state machine
api/routes/update.py	REST endpoints
api/schemas/update.py	Pydantic request/response models

Files to Modify

File	Change
api/__init__.py	Register update router
api/dependencies.py	Add get_update_service()
main.py	Create & start/stop UpdateService in lifespan
templates/modals/settings.html	Add Updates tab
static/js/features/settings.ts	Update check/settings UI logic
static/js/core/api.ts	Version badge highlight on health check
static/css/layout.css	.has-update styles for version badge
static/locales/en.json	i18n keys
static/locales/ru.json	i18n keys
static/locales/zh.json	i18n keys

Future Phases (not in scope)

• Phase 2: Download & stage artifacts
• Phase 3: Apply update & restart (external updater script, NSIS silent mode)
• Phase 4: Checksums, "What's new" dialog, update history