Життєвий цикл

Послідовність запуску

1. Main process запускає integrations worker (WorkerMain('integrations')) і чекає на loadComplete.
2. Main надсилає executeCode з { integration: { id, name, permissions, … }, codePath }.
3. Worker будує GenerateContext(), потім виконує index.js аддона у vm.runInContext (таймаут початкового виконання: 5 секунд).
4. Код аддона реєструє ендпоінти, схему конфігурації та обробники подій під час цієї фази завантаження.

Довготривала робота має продовжуватися після завантаження через setTimeout, setInterval, sleep або async-обробники — не блокуючий синхронний код під час початкового запуску VM.

Коли worker перезапускається

Worker перезапускається, коли:

• Користувач вимикає і знову вмикає аддон
• Аддон перевстановлюють або змінюють його файли (залежно від поведінки застосунку)
• З коду аддона викликається api.restart()
• Перемикається режим розробника (потрібен повний перезапуск застосунку/worker для поширення isDeveloperMode)

storage.Read() / storage.Write() зберігаються між перезапусками worker у межах одного встановлення. Параметри api.config зберігаються в конфігурації застосунку.

Коректна зупинка — addon:prepare-stop

Перед тим як StreamKit+ уб’є worker аддона, головний процес викликає вбудовану подію addon:prepare-stop і чекає завершення обробника (короткий таймаут, близько 2.5 секунд). Використовуйте її для віддаленого cleanup, поки ще доступні OAuth-токен і мережа.

Коли спрацьовує

• Користувач вимикає аддон у налаштуваннях
• Аддон видаляють (або деактивують як залежність під час видалення іншого аддона)
• Застосунок закривається (усі integration worker’и отримують prepare-stop перед kill)

Коли не спрацьовує

• Падіння / disconnect worker (немає часу на graceful-обробник)
• Раптове завершення процесу, коли головний процес не може дочекатися worker’ів

Контракт обробника

events.On('addon:prepare-stop', async () => {
  // наприклад поставити на паузу або вимкнути віддалені ресурси (нагороди Twitch, webhooks, …)
  await cleanupRemoteState();
  return { success: true };
});

Не покладайтеся на цю подію для даних, які мають жити вічно — важливий стан зберігайте через storage / api.config під час звичайної роботи. addon:prepare-stop — для best-effort teardown на боці зовнішніх сервісів (пауза нагород, закриття сесій, зняття короткоживучих хуків).

Див. також events.

Захист від циклу падінь

Якщо процес worker падає (неперехоплений виняток, фатальна помилка, аварійне завершення), StreamKit+ перезапускає його автоматично — як при звичайному рестарті.

Щоб уникнути нескінченного циклу перезапусків, застосунок відстежує послідовні падіння:

Що вважається падінням

• Завершення або відключення процесу worker
• Збій, виявлений health check головного процесу

Що не вважається падінням

• Помилки в колбеках setTimeout / setInterval та обробниках events.On — вони перехоплюються й логуються; worker продовжує працювати (див. Безпека)
• Плановий перезапуск через api.restart(), вимкнення/увімкнення аддона або ручний рестарт із налаштувань

Коли ліміт досягнуто

1. Автоперезапуск припиняється; worker аддона більше не запускається.
2. Користувач бачить сповіщення про помилку та статус аддона в стані error.
3. У налаштуваннях аддон залишається увімкненим, але показується бейдж Зупинено через помилки.
4. Після перезапуску застосунку аддон досі не стартує, доки користувач не вживе заходів.

Як відновити роботу

Користувач має перезапустити аддон вручну в налаштуваннях (кнопка ↻) або вимкнути й знову ввімкнути його. Це скидає прапорець зупинки й запускає новий worker з обнуленим лічильником падінь.

Що важливо автору аддона

• Не використовуйте падіння worker як спосіб відновлення — після трьох падінь аддон залишиться вимкненим до дії користувача.
• Тримайте початкову фазу завантаження index.js короткою; важку або ризиковану роботу переносьте в async-колбеки після завантаження.
• Обгортайте довготривалий код у try/catch; необроблені reject/throw поза обгорнутими пісочницею обробниками все ще можуть звалити worker.
• api.restart() працює лише поки аддон запущений; ним не можна перезапустити аддон, зупинений через цикл падінь.
• api.getProcessStats() повертає CPU, RAM і PID цього worker. Для CPU % потрібні щонайменше два виклики з інтервалом ~1 с; використовуйте для контролю витоків або виклику api.restart() при перевищенні лімітів.

Статичні web-маршрути

Коли встановлено manifest.web і надано WEB_CONTENT (або ROOT), main process реєструє статичні маршрути:

http://localhost:{WEB_SERVER_PORT}/addon_static/{id}/

Корінь обслуговує файл web; шляхи з web_contents доступні під тим самим префіксом. Маршрути видаляються при вимкненні, перезапуску або деінсталяції.

Відсутні файли

Якщо manifest.json або index.js відсутні за записаним шляхом встановлення, застосунок вважає аддон зламаним: у налаштуваннях показується банер помилки, налаштування не відкриваються, доступна лише деінсталяція. Тригери оверлею/таймера, що посилаються на цей аддон, очищуються під час запуску.