music-assistant-server

1# Background Tasks Controller
2
3This package contains the long-running task manager used for user-visible background work such as library syncs, playlist mutations, and other scheduled/system jobs.
4
5## Responsibilities
6
7- Register recurring scheduled tasks and keep them visible even while idle.
8- Queue and execute long-running ad hoc tasks with bounded concurrency.
9- Capture per-task in-memory log output for UI inspection and export.
10- Expose a task execution context so long-running code can report progress and non-fatal issues.
11- Publish task state changes through `EventType.TASKS_UPDATED`.
12- Retain only a limited history of completed ad hoc tasks in memory.
13- Persist scheduled-task runtime state such as `last_run` and pause/enable state.
14
15## Package Layout
16
17- `controller.py`: main `TasksController` orchestration, API handlers, queueing, and execution lifecycle.
18- `constants.py`: shared queue/log/retention constants and context variables.
19- `context.py`: runtime task-context helpers used by long-running code to report progress/issues.
20- `helpers.py`: reusable helper functions for visibility, sorting, retention, timer ids, and log capture.
21- `models.py`: runtime-only task state container used by the controller.
22
23## Design Notes
24
25- This controller is intentionally scoped to long-running work. Short-lived internal jobs should continue using `mass.create_task` and `mass.call_later`.
26- Scheduled tasks are retained in memory permanently; completed ad hoc tasks are retained only in a bounded history.
27- Progress/log churn is throttled before being mirrored onto the event bus, while lifecycle changes stay responsive.
28- Scheduled-task runtime state is persisted in the `tasks` core config under a dedicated raw value so restarts preserve `last_run`, failure state, and the enabled/disabled schedule flag.
29