rick/LEDMatrix
1
0
Fork 0
mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-10-04 14:25:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor(plugins): the display publishes plugin runtime state; retire plugin_state.json (#690)

Browse Source 
Stage 2 of the web plugin catalog, after #688.

- The display publishes a plugin runtime snapshot (plugin_runtime.py) to
  the shared cache: per plugin loaded, lifecycle state, a short redacted
  error summary, the version it loaded and when, plus published_at /
  stale_after / running. Written on change (throttled to 10 s; the
  RUNNING/ENABLED flip of an ordinary update is not a change) and once a
  minute otherwise; cleanup() publishes running: false.
- The web reads it back and restores loaded / state / error_info in
  /api/v3/plugins/installed (plus loaded_version, loaded_at and
  data.runtime). Only a live snapshot counts; stale, stopped or missing
  answers null and says which.
- data/plugin_state.json is retired: every reader and writer moved to
  config + disk (desired) or the snapshot (observed). Nothing in it was
  non-derivable, so nothing is migrated and an existing file is left
  unread. The web-side PluginStateManager (state_manager.py) is removed;
  the display's plugin_state.PluginStateManager is the only state machine.
- StateReconciliation compares config + disk with the snapshot, reporting
  enabled-but-not-loaded and older-version-loaded as no_action findings.
- Backups list installed manifests with enabled from config.json.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Chuck
2026-09-30 10:48:14 -04:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 7ab6fb1aff
commit b09434a418
38 changed files with 1893 additions and 940 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/plugin_system/plugin_state.py
+97 -4
View File
@@ -1,11 +1,14 @@
"""
Plugin State Management
Manages plugin state machine (loaded → enabled → running → error)
with state transitions and queries.
The display process's plugin state machine (loaded → enabled → running →
error), with state transitions and queries. It is the only record of plugin
lifecycle state: the web process runs no plugins, and reads this state as the
snapshot ``plugin_runtime.PluginRuntimePublisher`` publishes from it.
"""
import threading
import time
from enum import Enum
from typing import Optional, Dict, Any
from datetime import datetime
@@ -24,8 +27,27 @@ class PluginState(Enum):
DISABLED = "disabled" # Plugin is disabled in config
def published_state(state: PluginState) -> PluginState:
"""The state as readers outside the scheduler see it.
RUNNING is the scheduler's claim on a plugin for one update() call: every
update flips ENABLED -> RUNNING -> ENABLED. Published as is, that would be
a change -- and a cache write to the SD card -- on every plugin update, and
a reader would see a plugin blink between two states that mean the same
thing to it (loaded and taking part). Readers get ENABLED for both.
"""
return PluginState.ENABLED if state == PluginState.RUNNING else state
class PluginStateManager:
"""Manages plugin state transitions and queries."""
"""Manages plugin state transitions and queries.
Owned by the display process's PluginManager. ``change_count`` moves
whenever something a reader of the published snapshot would see changes
(published state, error info, the loaded record) and stays put across the
RUNNING/ENABLED flip of an ordinary update, so a publisher can tell
"nothing new" without diffing.
"""
def __init__(self, logger: Optional[logging.Logger] = None) -> None:
"""
@@ -41,6 +63,20 @@ class PluginStateManager:
self._state_transition_counts: Dict[str, int] = {}
self._error_info: Dict[str, Dict[str, Any]] = {}
self._last_update: Dict[str, datetime] = {}
# What load_plugin() registered: {'version', 'loaded_at'} per plugin
# whose instance is live. Cleared with the rest of its state on unload.
self._loaded: Dict[str, Dict[str, Any]] = {}
self._change_count = 0
@property
def change_count(self) -> int:
"""Moves on every change a published snapshot would show."""
with self._lock:
return self._change_count
def _note_change(self) -> None:
"""Count a reader-visible change. Callers must already hold ``_lock``."""
self._change_count += 1
def _record_transition(self, plugin_id: str) -> None:
"""Count a state transition. Callers must already hold ``_lock``."""
@@ -63,9 +99,12 @@ class PluginStateManager:
error: Optional error if transitioning to ERROR state
"""
with self._lock:
known = plugin_id in self._states
old_state = self._states.get(plugin_id, PluginState.UNLOADED)
self._states[plugin_id] = state
self._record_transition(plugin_id)
if not known or published_state(old_state) != published_state(state):
self._note_change()
# Store error info if transitioning to ERROR state
if state == PluginState.ERROR and error:
@@ -74,9 +113,11 @@ class PluginStateManager:
'error_type': type(error).__name__,
'timestamp': datetime.now()
}
self._note_change()
elif state != PluginState.ERROR:
# Clear error info when leaving ERROR state
self._error_info.pop(plugin_id, None)
if self._error_info.pop(plugin_id, None) is not None:
self._note_change()
self.logger.debug(
"Plugin %s state transition: %s → %s",
@@ -147,6 +188,7 @@ class PluginStateManager:
self._states[plugin_id] = state
self._record_transition(plugin_id)
self._error_info[plugin_id] = dict(error_info)
self._note_change()
self.logger.debug(
"Plugin %s state transition: %s → %s (recoverable error stored)",
@@ -173,6 +215,52 @@ class PluginStateManager:
info = self._error_info.get(plugin_id)
return dict(info) if info is not None else None
def record_loaded(self, plugin_id: str, version: Optional[str],
loaded_at: Optional[float] = None) -> None:
"""Record that ``plugin_id``'s instance is live, and which version.
Called by PluginManager.load_plugin() once the instance is registered;
clear_state() (unload) forgets it. ``version`` is the manifest's at
load time, which is what the display keeps running until it reloads
the plugin -- the version on disk can move on after a store update.
"""
with self._lock:
self._loaded[plugin_id] = {
'version': version,
'loaded_at': time.time() if loaded_at is None else loaded_at,
}
self._note_change()
def record_unloaded(self, plugin_id: str) -> None:
"""Forget the loaded record alone, keeping state and error info: for
an unload that failed after the instance was already dropped."""
with self._lock:
if self._loaded.pop(plugin_id, None) is not None:
self._note_change()
def runtime_records(self) -> Dict[str, Dict[str, Any]]:
"""Every known plugin's reader-visible state, taken in one critical
section so a concurrent load or unload is seen whole or not at all.
Per plugin: ``state`` (published_state()'s value), ``loaded``,
``version`` and ``loaded_at`` (None unless loaded) and ``error_info``
(a copy, or None).
"""
with self._lock:
records: Dict[str, Dict[str, Any]] = {}
for plugin_id in set(self._states) | set(self._loaded):
loaded = self._loaded.get(plugin_id)
info = self._error_info.get(plugin_id)
records[plugin_id] = {
'state': published_state(
self._states.get(plugin_id, PluginState.UNLOADED)).value,
'loaded': loaded is not None,
'version': loaded['version'] if loaded else None,
'loaded_at': loaded['loaded_at'] if loaded else None,
'error_info': dict(info) if info is not None else None,
}
return records
def record_update(self, plugin_id: str) -> None:
"""Record that plugin update() was called."""
self._last_update[plugin_id] = datetime.now()
@@ -221,8 +309,13 @@ class PluginStateManager:
state.
"""
with self._lock:
had = (plugin_id in self._states or plugin_id in self._loaded
or plugin_id in self._error_info)
self._states.pop(plugin_id, None)
self._state_transition_counts.pop(plugin_id, None)
self._error_info.pop(plugin_id, None)
self._last_update.pop(plugin_id, None)
self._loaded.pop(plugin_id, None)
if had:
self._note_change()