VNOX-Server/docs/design/plugins-and-marketplace.md

15 KiB
Raw Blame History

Vnox: серверные WASM-плагины и маркетплейс

Статус: архитектурное предложение по запросу пользователя. Реального runtime/API/маркетплейса пока нет. Старый VNOX-Server/docs/community/plugins.md описывает Deno/JS и пример modbot; новый план заменяет это направление после фиксации контракта.

Модель

Бот — это серверный плагин, которому выдана отдельная bot identity. Другие плагины могут только добавлять команды, расписания или обработку событий без видимого бота. Плагин устанавливает уполномоченный администратор конкретного сообщества; установка на один сервер не запускает его на всех клиентах или серверах.

Модератор, приветствия, опросы и игровая статистика — первые примеры. Музыкальные боты с декодированием/внешними источниками и обработка голосового содержимого — позднее расширение, не базовая возможность.

Runtime и общий API

Основной кандидат — Wasmtime в составе vnox-server. Общий версионированный контракт Vnox Plugin API описывается WIT; каждый поддержанный язык должен пройти одинаковые контрактные тесты. Один скомпилированный engine может переиспользоваться, но память/Store, права, очередь и состояние изолируются для каждого экземпляра плагина. Нельзя считать WASM защитой от любых ошибок host runtime.

Не давать по умолчанию WASI filesystem/sockets/environment/process access. Доступ к функциям Vnox идёт через узкие host interfaces: команды чата, события, ограниченное KV-хранилище, таймеры, настройки и разрешённые HTTP-запросы. Не использовать native DLL/so или Python/Lua без sandbox как основной формат маркетплейса.

Языки

Язык Способ Порядок
Rust Компиляция в WASM component, SDK с типами Plugin API Первый SDK и эталонные тесты
Lua Упакованный WASM-интерпретатор с Vnox-адаптером API Отдельный прототип после API; не обещать готовый прямой Lua→component toolchain
Python Component toolchain/упакованный interpreter, адаптер API Отдельный проверяемый этап; размер и холодный старт измеряются
JS/TS и другие Component toolchain и адаптер того же API По необходимости после первых SDK

Владельцу сервера не нужны установленные rustc, lua или python: устанавливается готовый пакет с runtime-зависимостями внутри. Исходники собираются у автора/в изолированном CI, а не произвольным install-script на сервере пользователя. Для Lua/Python нельзя обещать все пакеты pip, C-расширения или обычный OS API. Поддержка объявляется после работающего примера и измерения ресурсов, а не по одному наличию слова WASM.

События и исполнение

Плагин подписывается только на разрешённые события: slash-команда, вход/выход участника, сообщение разрешённого канала, изменение роли, таймер. Для slash-команд можно работать без доступа ко всей переписке. Доступ к содержимому чата — отдельное явно видимое разрешение, не автоматическая часть установки бота.

Очереди ограничены. Плагин не исполняется под глобальной блокировкой каналов или БД и не находится в критическом пути передачи голоса. На переполнение/таймаут предусмотрены отказ, счётчик ошибок и автоматическое отключение при повторении. Семантика повторной доставки и event_id документируется; side effects должны уметь дедуплицировать повтор события.

Синхронная премодерация, блокирующая публикацию сообщения до ответа плагина, если понадобится, получает отдельный контракт с лимитом времени и явным fail-open/fail-closed. Базовые асинхронные боты не задерживают принятие сообщения всеми остальными плагинами.

Разрешения

  • commands.register: заявить команды в своём namespace.
  • messages.send: писать от bot identity в выбранные каналы.
  • messages.read: получать содержимое только выбранных каналов.
  • messages.moderate: удалять/модерировать сообщения по политике сервера.
  • members.moderate: отдельные действия mute/kick/ban с ограничением иерархии.
  • storage.kv: ограниченное хранилище в namespace экземпляра.
  • timers.schedule: ограниченное количество задач.
  • http.fetch: запросы через host broker только к разрешённым назначениям.

Host проверяет права и scope на каждом вызове. Manifest описывает запрос, а не выдаёт полномочия. Контекст содержит plugin instance, bot actor и, для пользовательской команды, пользователя-инициатора; бот не может дать ему административные действия без отдельной проверки. Право управлять ролями не должно позволять назначить привилегии выше разрешённых боту.

Ключи Hub/server identity, сессии других пользователей, БД целиком, host env и глобальная E2EE-личка недоступны плагинам сообщества. События уже фильтруются до передачи в WASM. Если в будущем бот станет явным участником шифрованного разговора, это отдельная пользовательская модель с предупреждением, а не обход E2EE через admin API.

HTTP broker ограничивает URL/домены, редиректы, разрешённые адреса после DNS resolution, размер ответа, время и число запросов. Доступ к loopback, приватной инфраструктуре и cloud metadata закрыт по умолчанию. Fuel не ограничивает время зависшего host HTTP-вызова, поэтому ему нужны собственные timeout/cancellation и квоты.

Ограничение ресурсов

У каждого экземпляра есть потолок памяти/таблиц/стека, CPU budget с fuel/epoch interruption, время события, количество одновременных операций, глубина очереди, объём KV, логов и исходящего трафика. Значения определяются по измерению Rust/Lua/Python примеров; одинаковый лимит fuel может давать разные возможности интерпретируемому и компилируемому коду.

Ошибка/ловушка плагина завершает его обработчик, а не штатную работу сервера. Обновлять runtime по исправлениям безопасности. Не обещать защиту от всех багов самого Wasmtime/host; отделение runner в дочерний процесс может обсуждаться как дополнительная изоляция в рамках одной поставки, не как отдельная голосовая машина.

Пакет

Пакет .vnoxp: manifest, WASM component, ограниченные assets, лицензия и сведения о происхождении сборки. Manifest включает namespaced plugin_id, версию, поддерживаемый Plugin API, host compatibility, entrypoint, запрашиваемые права и config schema. Все составляющие перечислены с digest; версия immutable и не заменяется другим содержимым под тем же номером.

Архив безопасно распаковывается с лимитами количества/размера файлов, без path traversal, ссылок и исполняемых install hooks. Секреты конфигурации задаются владельцем отдельно и не попадают в опубликованный пакет или логи.

Маркетплейс на Hub

Hub хранит каталог авторов и плагинов, версии, пакеты, документацию, changelog, compatibility, требуемые права, жалобы и статусы публикации/отзыва. Пакеты хранятся по собственной release retention policy: правило DM-файлов «20 МБ / 4 дня» сюда не применяется.

Автор подписывает релиз. Подпись связывает пакет с автором и защищает целостность, но не доказывает отсутствие вредоносного поведения. Публикация проходит автоматическую проверку структуры/imports/лимитов и совместимости; для широких прав нужно отдельное рассмотрение. Отдельно показываются «автор подтверждён», «автоматические проверки пройдены» и «проверенная версия» с областью ревью. Не использовать общий значок «безопасно».

Первый маркетплейс бесплатный: каталог, установка, версии и права. Платежи/подписки не входят в MVP. Локальная установка файла остаётся доступной администратору с теми же проверками и sandbox; отсутствие Hub не останавливает уже установленный плагин.

Установка и обновление

  1. Администратор открывает каталог из управления сервером.
  2. Выбирает конкретную версию, читает права и назначает каналы/лимиты.
  3. Сам сервер скачивает пакет, проверяет manifest, совместимость, подписи/хэши и локально выданные права.
  4. Пакет запускается в изолированном экземпляре; настройки и состояние принадлежат этому экземпляру.
  5. По умолчанию обновления предлагаются, а не выполняются молча. Новые права никогда не принимаются автоматически.
  6. Обновление проверяется до переключения; rollback кода не должен портить KV после миграции схемы. Нужны версия схемы, согласованная миграция и snapshot только данных плагина.

Администратору доступны остановить/удалить, отозвать права/секреты, посмотреть ограниченные логи, CPU/память, ошибки и версию. Каталог может отозвать распространение опасной версии, но это не гарантирует её мгновенную остановку на офлайн-серверах; локальная политика обновления статуса задаётся явно.

План

  1. Общий контракт и модель авторизации, один Rust-плагин приветствий и slash-команда без чтения чата.
  2. Изоляция, квоты, таймеры, namespaced KV, обработка сбоев и повторов; негативные тесты.
  3. Lua SDK/runner, затем Python component: проверить общий API, нагрузку и зависимости.
  4. Установка локального подписанного пакета, lifecycle и обновления без расширения прав.
  5. Реестр пакетов Hub и управление установкой из клиента. JS/TS при наличии запроса.

До внедрения Plugin API сначала исправить права/протокол основной платформы: плагин не должен получать полномочия через существующие обходы handlers.

Первичные источники