Фоновые сервисы

Как сделать фоновый сервис: долгоживущий процесс с main(ctx), собственной базой SQLite, HTTP-интерфейсом для виджетов и запуском агентов по событиям.

Фоновый сервис это пакет с eva.kind: "background". Платформа запускает его как отдельный процесс в Package-pool и держит, пока он нужен. Сервис может работать по таймеру, хранить данные, ходить во внешние системы, отдавать виджеты и запускать агентов.

Минимальный сервис

{
  "name": "mail-watcher",
  "version": "1.0.0",
  "type": "module",
  "main": "index.js",
  "dependencies": { "@eva/widget-sdk": "*", "@eva/context": "*" },
  "eva": {
    "kind": "background",
    "title": "Наблюдатель почты",
    "description": "Следит за почтовым ящиком и запускает агента на новые письма",
    "widgets": [{ "id": "main", "path": "/", "title": "Входящие" }]
  }
}

import { createWidgetServer } from '@eva/widget-sdk';

export async function main(ctx) {
  const app = createWidgetServer(ctx);
  app.serve('public');

  app.get('/api/inbox', async (req, res) => {
    res.json({ items: await listNew(req.ctx.settings) });
  });

  setInterval(async () => {
    const letters = await fetchNew(ctx.settings);
    for (const letter of letters) {
      await ctx.startAgentJob('triage', { subject: letter.subject });
    }
  }, 5 * 60 * 1000);

  await app.listen();
}

Что даёт платформа

Возможность	Как пользоваться
Запуск и остановка	При публикации и кнопками Старт и Стоп. Состояние переживает перезапуск платформы
HTTP без своего порта	createWidgetServer(ctx), app.serve('public'), app.listen(). Платформа проксирует запросы к сервису сама
Своя база	ctx.db: один файл SQLite на пакет, принадлежит платформе
Настройки	Общие в ctx.settings процесса, личные в req.ctx.settings каждого запроса виджета
Запуск агентов	ctx.startAgentJob
Уведомления	ctx.notify({ title, message, open }): системное уведомление в Desktop. В облаке вызов ничего не показывает
Логи	console и ctx.logger попадают в лог сервиса

Общие и личные настройки

В main(ctx) у сервиса нет пользователя, поэтому там доступны только общие настройки и шаблоны без {{user.*}}. Чтение личного ключа из корневого контекста завершится ошибкой.

Личные значения, например токен Jira пользователя, приходят в каждый HTTP-запрос виджета после проверки входа: req.ctx.settings, третий аргумент обработчика или getContext().settings.

Debug-сервис

На вкладке Debug-сервис Студия запускает черновик параллельно с продом. Прод продолжает работать на активной версии, а debug-версия доступна по отдельному адресу /internal/bg-service-debug/<пакет>/. Здесь же видны логи. Виджеты черновика открываются на вкладке Виджеты.

Примеры

• Exchange Calendar: недельный календарь с личным паролем пользователя.
• Jira Widgets: канбан задач на SQLite и ворклоги.

Как устроены сами виджеты: Виджеты.