Lifecycle pluginu#

Przegląd#

INSTALL → LOAD → CONFIGURE → UNLOAD → 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#

┌─ INSTALL ─────────────────────────────────────┐
│ Download → Save to plugins/ → Save .vclu.json │
└───────────────────────┬───────────────────────┘
                        ▼
┌─ LOAD ────────────────────────────────────────┐
│ Sandbox → init.lua → Plugin:new()             │
│ → onInit(config)                              │
│ → start timers, pollers, subscriptions        │
└───────────────────────┬───────────────────────┘
                        ▼
┌─ RUNNING ─────────────────────────────────────┐
│ Plugin aktywny: pollery, eventy, HTTP, MQTT   │
│                                               │
│ CONFIG CHANGE → unload → load (z nowym cfg)   │
└───────────────────────┬───────────────────────┘
                        ▼
┌─ UNLOAD ──────────────────────────────────────┐
│ onCleanup() → auto-cleanup zasobów            │
│ → clear timers → unsub events → unsub MQTT    │
│ → delete registry objects → clear throttle    │
└───────────────────────┬───────────────────────┘
                        ▼
┌─ UNINSTALL ───────────────────────────────────┐
│ Remove from .vclu.json (dir stays on disk)    │
└───────────────────────────────────────────────┘