Aurobore

Тема

Plugin API (архитектура) ​

Соответствует пункту 5 задачи: что такое плагин, какие сущности входят, как происходит регистрация и загрузка, как взаимодействуют Runtime ↔ Plugin ↔ JS. Только архитектура, без реализации. Базовое решение — ADR-003. См. также plugin-system.md.

Plugin API — контракт, по которому третья сторона (или core-команда) расширяет платформу нативной возможностью и её типизированным JS-интерфейсом. Главная идея: плагин = декларативный манифест, из которого автоматически выводятся все слои.

1. Что такое плагин ​

Плагин — самодостаточный модуль, состоящий из:

  1. Манифеста — контракт (методы, события, типы, разрешения, нативные зависимости, совместимость).
  2. Нативной реализации (C++/QML) — то, что автор пишет вручную (полезная логика).
  3. Сгенерированной JS-обёртки — типизированный вызов методов/подписок (кодоген из манифеста).
  4. Сгенерированных TS-типов — для автодополнения и проверки.
  5. Метаданных дистрибуции — для публикации (npm) и установки.
  6. Документации/примеров (желательно).
@aurobore/camera/
├── plugin.manifest        # SoT: контракт
├── native/                # C++/QML — автор пишет
│   ├── camera.<cpp/h>
│   └── camera.qml (если нужно)
├── generated/             # КОДОГЕН: js-обёртка + .d.ts (не редактировать)
├── package metadata       # дистрибуция (npm)
└── docs/ examples/

2. Сущности, входящие в плагин ​

СущностьОписание
Identityname, npm-имя, display (→ Aurobore.<Display>), version (semver).
MethodsВызываемые из JS операции: имя, схема args, схема result, признак стрима, отменяемость.
EventsИмена событий и схемы их данных, эмитируемых плагином в JS.
TypesПереиспользуемые структуры данных (используются в methods/events) → TS-типы.
PermissionsТребуемые системные разрешения.
ScopesУточнение разрешений (границы доступа).
NativeDepsRPM/Qt-зависимости для .spec/CMake.
CompatСовместимость с Runtime/протоколом моста, минимальная версия ОС, движки.

3. Как происходит регистрация ​

Регистрация — двухфазная (build-time + runtime), см. plugin-loader.md:

Build-time:

1. Плагин установлен (aurobore plugin add) → попал в aurobore.config / зависимости.
2. Build System читает манифест:
   • генерирует JS-обёртку и TS-типы;
   • добавляет nativeDeps в .spec/CMake;
   • агрегирует permissions в .desktop;
   • включает плагин в нативный «реестр» контейнера.

Runtime (старт приложения):

3. Plugin Loader читает реестр, проверяет совместимость.
4. Инстанцирует нативный объект плагина, регистрирует методы/события в Plugin Manager.
5. Bridge(JS) публикует Aurobore.<Plugin> в WebView ДО загрузки приложения.

Никакой ручной правки нативных конфигов и динамической загрузки произвольного кода — регистрация статична и безопасна (см. ADR-003).

4. Как происходит загрузка ​

  • Загрузка = инстанцирование + регистрация на старте Runtime (см. выше, шаги 3–5).
  • Несовместимые плагины пропускаются с понятной диагностикой (Runtime не падает).
  • Доступность методов/событий публикуется в JS-реестре (Aurobore.__plugins) для интроспекции и DevTools.

5. Взаимодействие Runtime ↔ Plugin ↔ JS ​

Вызов метода (JS → Plugin) ​

JS:      Camera.getPhoto(args)
SDK:     invoke({plugin:"Camera", method:"getPhoto", args, id})
Bridge:  транспорт → native; валидация версии/разрешений/области/схемы args
Manager: маршрут → CameraPlugin.getPhoto(context)
Plugin:  native-работа (Qt/Aurora API), async; context.resolve(result) | context.fail(...)
Bridge:  response{id, ok|error} → JS; Promise резолвится/реджектится

Событие (Plugin → JS) ​

Plugin:  context.emit("network:change", data)
Bridge:  event{name, data} → JS
SDK:     доставка подписчикам Aurobore.on("network:change", …)

Стрим (Plugin ↔ JS) ​

JS:      Geolocation.watch(cb)  →  подписка (subscriptionId)
Plugin:  стартует источник; sub.data(...) многократно; sub.error/complete
JS:      cb вызывается на каждое; sub.stop() → teardown источника

См. детали жизненного цикла в bridge.md и event-system.md.

6. Контракт автора плагина (минимум) ​

  1. Написать манифест (что плагин предоставляет).
  2. Реализовать нативную часть по контракту Native SDK: методы, эмиссия событий/стримов, возврат структурированных ошибок.
  3. (Опционально) добавить документацию/примеры.
  4. JS-обёртка и типы — генерируются, вручную не пишутся.

7. Версионирование и совместимость API ​

  • Плагин — semver; ломающие изменения методов/типов → мажорная версия.
  • Манифест объявляет диапазон совместимых версий Runtime/протокола → проверка при загрузке.
  • Депрекация: метод можно пометить устаревшим в манифесте (отражается в типах/доках) до удаления.

8. Тестирование плагинов ​

  • Conformance suite (SHOULD, FR-T1): набор тестов, проверяющих, что плагин соответствует манифесту и корректно обрабатывает ошибки/разрешения/стримы.
  • Возможность тестировать нативную логику изолированно и мост — через loopback-транспорт.

9. Связи ​