Native SDK (нативный SDK для авторов плагинов)
Реализация MVP (M3): код и контракты — runtime/native-sdk/README.md. Ниже — архитектурное описание (концепции, целевое API).
Контракты и библиотека для написания нативной части плагинов (C++/QML). Архитектура без привязки к конкретным файлам репо.
Native SDK — это то, на что опирается автор плагина, реализуя нативную часть. Он определяет контракты, которые Plugin Manager ожидает от плагина, и предоставляет вспомогательные средства (сериализация, эмиссия событий/стримов, доступ к контексту приложения), чтобы автор писал только полезную логику, а не инфраструктуру моста.
1. Что предоставляет Native SDK
| Элемент | Назначение |
|---|---|
| Контракт плагина | Базовый интерфейс/контракт, который реализует нативный класс плагина (методы, инициализация, teardown). |
| Регистрация методов | Способ объявить методы, вызываемые из JS (имя → обработчик), сопоставимый с манифестом. |
| Контекст вызова | Объект с аргументами (десериализованными), способом вернуть результат/ошибку, информацией о вызывающем (разрешения/область). |
| Эмиссия событий/стримов | API для отправки событий в JS и управления подписками/стримами (data/error/complete). |
| Сериализация | Хелперы конвертации между нативными типами и форматом моста. |
| Доступ к среде | Контролируемый доступ к контексту приложения Аврора, lifecycle, разрешениям. |
| Обработка ошибок | Способ вернуть структурированную ошибку моста (код/сообщение/данные) вместо исключения. |
| Асинхронность | Поддержка длительных операций вне UI-потока без блокировки Runtime. |
2. Контракт «метод плагина» (концептуально)
// псевдоконтракт, не реализация
PluginMethod(context):
args = context.args // десериализованные аргументы (валидированы по манифесту)
if not context.hasPermission(...): context.fail("CAMERA_PERMISSION_DENIED", ...)
result = doNativeWork(args) // возможно async, вне UI-потока
context.resolve(result) // или context.fail(code, message, data)3. Контракт «событие/стрим» (концептуально)
// событие
context.emit("network:change", { online: true })
// стрим
sub = context.openStream(subscriptionId)
sub.data({ lat, lon }) // многократно
sub.error(code, message) // при ошибке
sub.complete() // завершение
// при отписке из JS SDK вызывает teardown стрима — источник останавливается4. Соответствие манифесту
- Манифест — контракт; нативная реализация обязана соответствовать объявленным методам/событиям/типам.
- Несоответствие выявляется кодогенерацией/проверками сборки (заготовки регистрации генерируются из манифеста).
- Это сохраняет принцип SoT: меняется манифест → меняются и ожидания к нативной части.
5. Изоляция и устойчивость
- Ошибки/исключения нативной части перехватываются и превращаются в ошибки моста (NFR-7), не роняя Runtime.
- Длительные операции — асинхронны; UI-поток не блокируется.
- Освобождение ресурсов (стримы, хэндлы) гарантируется при отписке/выгрузке/lifecycle-событиях.
6. Нативные зависимости и движки
- Плагин объявляет нативные зависимости (
nativeDeps) и поддерживаемые движки (auroraCompat.engines) в манифесте; Build System включает их в.spec/CMake. - Если возможность зависит от движка/версии ОС, автор обрабатывает различия и возвращает
*_UNAVAILABLEтам, где функция недоступна.
7. Связи
- ↔ Plugin System — модель и манифест.
- ↔ Plugin Loader — регистрация и вызов.
- ↔ Bridge — формат сообщений/ошибок/стримов.
- ↔ TypeScript SDK — парная JS-сторона контракта.
- ↔ Build System — включение нативной части и зависимостей.