Runtime (нативный контейнер)
Соответствует пункту 8 задачи. Описание архитектуры, без реализации. Базовое решение зафиксировано в ADR-001.
Runtime — «сердце» платформы на устройстве. Это нативное приложение Аврора (C++/QML), которое запускает WebView с веб-приложением пользователя и предоставляет ему контролируемый доступ к системе через Bridge и плагины.
1. Зоны ответственности
- Запуск приложения и инициализация окна Аврора (ApplicationWindow, pageStack, cover).
- Создание и конфигурация WebView на CEF/Chromium через тонкий шов транспорта (ADR-004).
- Подъём native-стороны Bridge и Plugin Loader.
- Обслуживание жизненного цикла, навигации, splash screen, asset loader, разрешений, deep links.
- Маршрутизация вызовов и событий между WebView и плагинами.
- Гарантия устойчивости: исключение в плагине не должно ронять контейнер.
Runtime не содержит бизнес-логики приложения и не реализует конкретные нативные возможности — это делают плагины. Runtime — оркестратор.
2. Запуск приложения (bootstrap)
Последовательность старта:
1. Старт нативного процесса (точка входа C++).
2. Чтение встроенной конфигурации приложения (производная от aurobore.config).
3. Инициализация окна Аврора и показ Splash Screen.
4. Создание WebView нужного движка (определяется на этапе сборки/рантайма).
5. Инициализация Bridge (native-сторона) и Transport под текущий движок.
6. Plugin Loader: обнаружение плагинов, проверка совместимости, регистрация в Plugin Manager.
7. Инъекция JS-стороны Bridge и реестра плагинов в контекст WebView (до загрузки приложения).
8. Asset Loader: регистрация безопасной схемы для локальных ресурсов.
9. Загрузка веб-приложения (локально из пакета или с Dev Server в режиме разработки).
10. Ожидание сигнала готовности от веб-приложения → скрытие Splash Screen.
11. Эмиссия события lifecycle "ready"/"resume".3. WebView
- WebView — встраиваемый веб-компонент Аврора. Целевой движок — Chromium/CEF (
ru.auroraos.webview); Gecko (легаси) не поддерживается (ADR-004). - Конфигурация WebView: размеры/ориентация, политика навигации, обработка внешних ссылок, user-agent, доступ к сети, инъекция bridge-скрипта до контента.
- Внешние ссылки (http/https на чужие домены) по умолчанию открываются во внешнем браузере либо блокируются согласно политике безопасности; внутренние переходы остаются в WebView.
Шов транспорта
Runtime определяет внутренний интерфейс транспорта моста с единственной реальной реализацией на WebView async API (sendAsyncMessage/onRecvAsyncMessage/runJavaScript, ru.auroraos.WebView) плюс loopback-двойник для тестов. CEF CefMessageRouter/cefQuery — деталь реализации ниже. Шов — write-once, нужен для тестируемости и изоляции изменений CEF/qtium-driver, а не для второй платформы. Подробнее — Bridge Transport и ADR-004.
4. Splash Screen
- Показывается сразу при старте, до готовности веб-приложения, чтобы скрыть «белый экран».
- Внешний вид (изображение, фон, индикатор) задаётся конфигом.
- Скрывается автоматически по сигналу готовности от веб-приложения или по таймауту (fallback), чтобы не «зависнуть» на splash при ошибке загрузки.
- Управляется и из JS (например, отложить скрытие до прогрева данных) через системный плагин/событие.
5. Жизненный цикл (Lifecycle)
Runtime отражает системные события Аврора в единый набор событий приложения и доставляет их в JS через Event System:
| Событие | Когда |
|---|---|
ready | Runtime готов, bridge поднят, приложение загружено |
pause | Приложение уходит в фон |
resume | Приложение возвращается на передний план |
backbutton | Нажата аппаратная/системная кнопка «назад» |
memoryWarning | Система сигнализирует о нехватке памяти |
orientationchange | Сменилась ориентация |
destroy | Приложение завершает работу |
Веб-приложение подписывается: Aurobore.on("pause", handler). Поведение по умолчанию для backbutton (например, навигация назад в SPA) — переопределяемо.
6. Навигация
- Поддержка SPA и History API: переходы внутри приложения не перезагружают WebView.
- Аппаратная «назад» сопоставляется с историей навигации; если истории нет — поведение по умолчанию (свернуть/закрыть), переопределяемое приложением.
- Политика навигации: разрешённые источники, поведение для внешних URL, обработка
target=_blank. - Состояние навигации сохраняется при pause/resume в пределах сессии.
7. Asset Loader
Цель — отдавать локальные веб-ресурсы без сырого file:// для entry: единый origin для SPA, контроль навигации, безопасность (как tauri:// / capacitor:// / asset://).
- Базовый путь — каталог веб-ресурсов внутри пакета приложения.
- В режиме разработки источником может быть Dev Server (http://localhost:port).
- Поддержка корректных MIME-типов, кэширования и (при необходимости) range-запросов для медиа.
- Область доступа ограничена ресурсами приложения (без обхода файловой системы устройства).
M1 (текущая реализация)
Прямой CefRegisterSchemeHandlerFactory недоступен в public SDK (V-13). Реализован loopback HTTPS (AssetSchemeServer на https://127.0.0.1:<port>/) с маппингом путей через AssetResolver. Логический ключ entry в конфиге — aurobore-app://localhost/…; WebView грузит loopback URL. Самоподписанный сертификат доверяется через InitBrowser(ignore-certificate-errors) без участия пользователя. См. runtime/container/README.md.
Целевая схема (post-M1)
Кастомная схема aurobore-app:// на wire-уровне (CEF scheme handler), если OMP откроет API.
8. Разрешения (Permissions)
- Разрешения приложения декларируются в конфиге и проецируются в артефакты Аврора (например,
Internetв.desktop) на этапе сборки. - Runtime сопоставляет запрашиваемые плагином возможности с разрешениями приложения; вызов без соответствующего разрешения отклоняется с понятной ошибкой ещё на мосту.
- Рантайм-запросы согласия пользователя (где это модель Аврора) инициируются плагином через системный API.
- Область (scope) уточняет разрешение (например, FS — только каталог данных приложения). См. также модель безопасности в bridge.md.
9. Deep Links
- Регистрация кастомной URI-схемы/паттернов приложения на этапе сборки (через
.desktop/манифест Аврора). - При старте по ссылке Runtime передаёт исходный URI в JS как событие (
appurlopen/deeplink). - Если приложение уже запущено — deep link доставляется как событие resume + URL.
- Маршрутизация внутри приложения — ответственность веб-приложения (его роутер).
10. Обложка (cover)
На домашнем экране Авроры фоновое приложение показывается через нативную обложку (ApplicationWindow.cover), а не через WebView.
| Режим | Поведение |
|---|---|
| По умолчанию | CoverTemplate с именем приложения (app.name); без кода и без секции cover в конфиге |
| Opt-in | cover.actions в конфиге; runtime API Cover.setState / setActions / reset через мост |
| События | cover:action (tap на кнопке), cover:active / cover:inactive |
Реализация: CoverBridge (QObject, биндинги QML) + встроенный плагин Cover (не в plugins[] пользователя). QML: qml/cover/DefaultCover.qml.
Подробнее: api/cover.md.
11. Устойчивость и ошибки
- Вызовы плагинов выполняются так, чтобы исключение/паника плагина превращалась в структурированную ошибку моста (reject Promise), а не в падение Runtime (NFR-7).
- Долгие операции выполняются вне UI-потока; Runtime не блокирует рендеринг.
- Журналирование: ошибки Runtime, плагинов и моста логируются с кодами и пространствами имён (NFR-12).
12. Связи с другими компонентами
- ↔ Bridge: Runtime владеет native-стороной моста и транспортом.
- ↔ Plugin Loader / Plugin System: Runtime загружает и вызывает плагины.
- ↔ Event System: Runtime — источник системных событий.
- ↔ Configuration: встроенная конфигурация — производная от
aurobore.config. - ↔ Build System: Runtime поставляется как генерируемый нативный проект-контейнер.
13. OTA / Live Updates (FR-R13)
Опциональная подсистема UpdateManager в контейнере (runtime/container):
- Периодическая или on-resume проверка канала обновлений (
updates.url+channel). - Скачивание подписанного бандла, проверка Ed25519-подписи манифеста.
- Атомарная подмена активного веб-бандла; откат к предыдущей версии при сбое.
- События
update:available,update:readyи др. доставляются в JS через мост.
Обновляется только веб-часть; смена нативного слоя и permissions — по-прежнему через RPM. См. ADR-012, dev/ota-updates.md.