99 lines
15 KiB
Markdown
99 lines
15 KiB
Markdown
# 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
|