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

99 lines
15 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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.
## Первичные источники
- Wasmtime security: https://docs.wasmtime.dev/security.html
- Fuel/epoch interruption: https://docs.wasmtime.dev/examples-interrupting-wasm.html
- Component language support: https://component-model.bytecodealliance.org/language-support.html
- WIT interfaces: https://component-model.bytecodealliance.org/design/wit.html