Lifecycle pluginu#

Przegląd#

graph LR
    A[INSTALL] --> B[LOAD] --> C[CONFIGURE] --> D[UNLOAD] --> E[UNINSTALL]

Install#

1. Użytkownik wybiera plugin w UI (/plugins) lub POST /api/plugins/install
2. Loader pobiera plugin.json + pliki z repozytorium
3. Zapisuje do plugins/{namespace}--{shortId}/
4. Dodaje wpis w .vclu.json → plugins.installed[] z config={}
5. Plugin nie jest ładowany - wymaga konfiguracji i włączenia

POST /api/plugins/install
{
  "id": "weather",
  "fullId": "@vclu/weather",
  "repository": "vCLU Official"
}

Load#

Wywoływany przy:

• Starcie serwera (wszystkie enabled pluginy)
• Włączeniu pluginu (POST /plugins/:id/toggle)
• Zmianie konfiguracji (POST /plugins/:id/config)

Kroki:

1. Odczyt plugin.json (manifest)
2. Utworzenie izolowanego środowiska Lua
3. Przekazanie konfiguracji z .vclu.json
4. Załadowanie init.lua w sandboxie
5. Wywołanie onInit(config) callback
6. Plugin startuje timery, pollery, subskrypcje

Configure#

1. Użytkownik wypełnia formularz w UI (generowany z configSchema)
2. POST /api/plugins/:id/config z nowym obiektem config
3. Config zapisywany do .vclu.json
4. Jeśli plugin enabled:
   • Unload - cleanup starego
   • Load - załadowanie z nową konfiguracją
5. Jeśli plugin disabled - tylko zapis config

POST /api/plugins/@vclu/weather/config
{
  "config": {
    "apiKey": "new-key",
    "city": "Kraków"
  }
}

Unload#

Wywoływany przy:

• Wyłączeniu pluginu (POST /plugins/:id/toggle)
• Odinstalowaniu (DELETE /plugins/:id)
• Wyłączeniu serwera
• Zmianie konfiguracji (przed reload)

Kroki:

1. Wywołanie onCleanup() callback pluginu
2. Automatyczne czyszczenie zasobów:
   • Usunięcie wszystkich timerów
   • Wyrejestrowanie event subscriptions
   • Wyrejestrowanie MQTT subscriptions
   • Usunięcie obiektów z registry
   • Wyczyszczenie throttle state
3. Usunięcie instancji pluginu

-- Przykład onCleanup:
plugin:onCleanup(function()
    plugin:log("info", "Cleaning up...")
    -- Polery i timery auto-czyszczone
    -- Wystarczy cleanup własnych zasobów
end)

Uninstall#

1. DELETE /api/plugins/:id
2. Jeśli enabled → unload (cleanup)
3. Usunięcie z .vclu.json → plugins.installed[]
4. Katalog pluginu pozostaje na dysku (możliwy reinstall)
5. Opcjonalnie: usunięcie pliku KV store

Diagram#

graph TD
    install["INSTALL<br/><i>Download → Save to plugins/<br/>→ Save .vclu.json</i>"]
    load["LOAD<br/><i>Sandbox → init.lua → Plugin:new()<br/>→ onInit(config)<br/>→ start timers, pollers, subscriptions</i>"]
    running["RUNNING<br/><i>Plugin aktywny: pollery, eventy, HTTP, MQTT<br/>CONFIG CHANGE → unload → load (z nowym cfg)</i>"]
    unload["UNLOAD<br/><i>onCleanup() → auto-cleanup zasobów<br/>→ clear timers → unsub events → unsub MQTT<br/>→ delete registry objects → clear throttle</i>"]
    uninstall["UNINSTALL<br/><i>Remove from .vclu.json<br/>(dir stays on disk)</i>"]

    install --> load --> running --> unload --> uninstall