kk0t9
d112f5397d
C-shell v2: - GPS-скорость для distraction — домен K (ru.shturman.Location), не E (E это OBD, v2); E — уточнение OBD-скорости в v2 + быстрый статус машины - механизм поверхности: Wayland slot-протокол ru.shturman.shell_slot + slot-token, не «handle по D-Bus» - fail-safe distraction при потере/устаревании скорости (консервативный дефолт, гистерезис, арбитраж GPS/OBD) - контракт статус-бара: network «unknown» до Connectivity; часы — до синка времени Кросс-док: - architecture §1 (ELM327-оговорка к «физическому» read-only), §5 (положение/GPS из Location/K, не Vehicle-Data), §7 (Perm-Broker = грантодатель, статика — прокси+sandbox), §8 (surface через Wayland slot-протокол) - ipc Shell.RegisterScreen → slot_token - dev-environment: cage → smithay/weston в журнале и списке пакетов Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
157 lines
16 KiB
Markdown
157 lines
16 KiB
Markdown
# Контракт: IPC (D-Bus)
|
||
|
||
> Backbone связей: реестр D-Bus-сервисов, их интерфейсов и соглашений.
|
||
> Формализует карту связей из [architecture.md](../architecture.md) §5 в конкретные
|
||
> контракты. К нему цепляются data-model, plugin-sdk и все домены.
|
||
|
||
Статус: **v2 (на ревью).** v2 — после ретро-ревью (10 находок).
|
||
Связано с: [architecture.md](../architecture.md) (§4–5) · [data-model.md](data-model.md) · [plugin-sdk.md](plugin-sdk.md) · [security-privacy.md](security-privacy.md)
|
||
|
||
Область: **control plane** (D-Bus). Аудио/видео/графика — НЕ здесь (PipeWire/Wayland, см. architecture §4).
|
||
|
||
---
|
||
|
||
## 1. Шина и топология
|
||
|
||
- **Одна системная шина устройства** (Штурман — single-purpose appliance, системная шина *и есть* его шина) со строгой D-Bus-политикой.
|
||
- Ядро-сервисы общаются на ней напрямую.
|
||
- **Песочные апы/плагины напрямую шину НЕ видят** — каждому выдаётся
|
||
**фильтрующий D-Bus-прокси** (паттерн `xdg-dbus-proxy`), настроенный App-Host'ом
|
||
из capabilities манифеста (см. §5). Это реализация портал-модели из решения №5.
|
||
|
||
> 🟡 *Мелкий выбор на подтверждение:* системная шина устройства (рекомендую,
|
||
> проще) vs выделенный экземпляр `dbus-daemon` только для Штурмана (чище изоляция
|
||
> от хост-сервисов, но лишний компонент). Прокси-фильтрация даёт изоляцию в обоих
|
||
> случаях.
|
||
|
||
## 2. Соглашения
|
||
|
||
| Аспект | Правило |
|
||
|--------|---------|
|
||
| Well-known имя | `ru.shturman.<Service>` (напр. `ru.shturman.VehicleData`) |
|
||
| Путь объекта | `/ru/shturman/<Service>` |
|
||
| Интерфейс | `ru.shturman.<Service>N` — `N` = мажорная версия (напр. `…VehicleData1`) |
|
||
| Версионирование | аддитивно внутри версии; ломающее → **добавляется** `…2` рядом со старым `…1`; оба сосуществуют в окне поддержки (старые плагины работают без правок; EOL мажора синхронизируется с `shturman_api` в манифесте) |
|
||
| Ошибки | `ru.shturman.Error.<Name>`: `PermissionDenied`, `NotAvailable` (PID не поддержан машиной — постоянно), `Stale`/`Timeout` (транзиентно: таймаут/устарело), `ReadOnly`, `InvalidArgument`, `Unsupported` |
|
||
| Действие | **метод** |
|
||
| Изменение состояния | **сигнал** |
|
||
| Текущее состояние | **property** (+ стандартный `PropertiesChanged`) |
|
||
| Асинхронность | всё async (zbus + tokio); долгие операции не блокируют |
|
||
| Стандартные интерфейсы | `org.freedesktop.DBus.{Properties,Introspectable,Peer}` |
|
||
| Идентичность вызывающего | по **аутентифицированному соединению** (`sender` → PID/cgroup → манифест, привязка App-Host'ом), НЕ по аргументу метода; подменить нельзя |
|
||
| Жизненный цикл клиент-состояния | серверное состояние клиента (подписки, регистрации тайлов/интентов) **снимается автоматически** при исчезновении владельца имени (`NameOwnerChanged`) — крэш/рестарт не оставляет мусора |
|
||
|
||
> Полные сигнатуры (XML-интроспекция) фиксируются при реализации; здесь — реестр и ключевые члены.
|
||
|
||
---
|
||
|
||
## 3. Реестр сервисов — ядро (привилегированные)
|
||
|
||
### `ru.shturman.VehicleData` — данные машины (**READ-ONLY**)
|
||
- **Методы (только чтение):** `ListSignals() → [(name, availability)]`, `GetSignal(name) → (value, unit, ts, quality)`, `Subscribe(names, desired_max_hz)`/`Unsubscribe(names)`, `GetDtcs() → [(code, status, desc)]`.
|
||
- **Авторизация по имени сигнала — в самом сервисе:** прокси (§5) не видит payload, поэтому `vehicle_read:[…]` enforce-ит **VehicleData по идентичности вызывающего** (`sender` → манифест), отвергая незаявленные имена `PermissionDenied`. Сигналы **адресные**: `SignalChanged(name, value, ts, quality)` шлётся только подписчику и только по `Subscribe ∩ манифест`; `DtcsChanged([...])`.
|
||
- **Частота:** `desired_max_hz` — верхняя граница, которую готов принять подписчик, и вход в **агрегатный** опрос: фактический опрос PID = `max()` запрошенных, ограничен потолком шины (~10–20 Гц) и источником. Доставка индивидуально не троттлится — слабый клиент (приборка) прореживает сам. Имя `desired_` подчёркивает: не гарантия «моей частоты».
|
||
- **Подписки привязаны к владельцу соединения** — снимаются автоматически при крэше/рестарте; агрегатный опрос пересчитывается, опрос PID останавливается без живых подписчиков (бережёт скудный ELM327).
|
||
- **Таймаут/staleness:** `GetSignal` имеет таймаут → `Stale`/`Timeout` (или stale-flag в `quality`), не виснет на медленном ELM327-PID. `NotAvailable` = PID не поддержан машиной (постоянно); `Stale` = транзиентно (двигатель заглушен/таймаут).
|
||
- **Properties (горячие):** `Speed`, `Rpm`, `CoolantTemp`, `ModuleVoltage` (питание ЭБУ ≈ бортсеть, не клеммы АКБ), `Online`.
|
||
- ⛔ **Методов записи нет** — ни `SetSignal`, ни actuator-команд, ни clear-DTC. Архитектурная гарантия read-only (принцип #2). Типы — [data-model.md](data-model.md).
|
||
|
||
### `ru.shturman.Power` — питание и жизненный цикл
|
||
- **Методы:** `GetPowerState() → state`, `RequestSleep()` (внутр.).
|
||
- **Сигналы:** `AccChanged(on)`, `ShutdownImminent(seconds)`, `Sleep()`, `Wake()`.
|
||
- **Properties:** `IgnitionState`, `Uptime`, `PowerSource`.
|
||
|
||
### `ru.shturman.Settings` — конфигурация и состояние
|
||
- **Методы:** `Get(key) → value`, `Set(key, value)`, `List(prefix) → [key]`, `Reset(key)`.
|
||
- **Сигналы:** `Changed(key, value)`.
|
||
- **Namespace изолирует сам сервис Settings** по идентичности вызывающего (`sender` → app-id): Get/Set/List/Reset вне своего namespace → `PermissionDenied` (прокси этого не делает — не инспектирует строку `key`). Свой namespace — read/write по умолчанию (ambient, без отдельной capability).
|
||
|
||
### `ru.shturman.PermBroker` — политика разрешений (привратник)
|
||
- **Идентичность — только из соединения** (`sender` → манифест), **никогда из аргумента** (иначе спуфинг/проверка за чужой ап).
|
||
- **Методы:** `CheckCapability(cap) → bool` (sender-scoped — ап спрашивает про СЕБЯ; кросс-ап форма доступна только привилегированным core по D-Bus-политике), `RequestRuntimeGrant(cap) → granted` (рантайм-промпт; целевой ап = `sender`).
|
||
- **Сигналы:** `GrantChanged(cap, granted)` — адресно владельцу гранта (чужие не получают).
|
||
- Статическая фильтрация — прокси + sandbox (§5, владеет App-Host); broker — политика и рантайм-согласия.
|
||
|
||
### `ru.shturman.AppHost` — запуск/супервизия апов и плагинов
|
||
- **Методы:** `ListApps() → [(id, status)]`, `StartApp(id)`, `StopApp(id)`, `GetStatus(id) → status`.
|
||
- **Сигналы:** `AppStarted(id)`, `AppStopped(id)`, `AppCrashed(id, reason)`.
|
||
- (Установка/дистрибуция плагинов — домен F, не здесь.)
|
||
|
||
### `ru.shturman.Connectivity` — сеть (обёртка NM/MM)
|
||
- **Методы:** `GetStatus() → status`, `ListNetworks() → [...]`, `Connect(id)`, `Disconnect()`.
|
||
- **Сигналы:** `ConnectivityChanged(online)`, `NetworkChanged(...)`.
|
||
- **Properties:** `Online` (bool — «сервис ещё не поднят» ≠ «offline»), `Type` (wifi/modem), `SignalStrength`.
|
||
|
||
### `ru.shturman.Location` — GPS/положение (владелец — домен K)
|
||
- **Properties:** `Latitude`, `Longitude`, `Heading`, `Speed` (GPS-скорость), `FixQuality`, `ts`.
|
||
- **Сигналы:** `LocationChanged(...)`, `FixChanged(quality)`.
|
||
- Источник — NMEA/gpsd (hardware §4); гейтится capability `location`. **GPS-скорость берётся ОТСЮДА** (не из VehicleData/E — E это CAN/OBD, появляется в v2). До домена K — мок-стаб (dev fake-GPS).
|
||
|
||
---
|
||
|
||
## 4. Реестр сервисов — апы (на SDK)
|
||
|
||
### `ru.shturman.Assistant`
|
||
- **Методы:** `SendText(query) → reply`, `StartListening()`, `StopListening()`, `RegisterIntents(handler_path)` — привязывает handler к фразам **из манифеста** `assistant_intents` (фразы НЕ передаются в рантайме, иначе обходится install-ревью).
|
||
- **Сигналы:** `StateChanged(idle|listening|thinking|speaking)`, `TranscriptUpdated(text)`, `ReplyUpdated(text)`.
|
||
- Контекст машины подмешивается ассистентом из `VehicleData` (см. architecture §5).
|
||
|
||
### `ru.shturman.Shell` — UX-host (слот-модель, решение №6)
|
||
- **Методы:** `RegisterTile(decl)`, `RegisterScreen(decl) → slot_token` (для поверхности клиент предъявляет slot-token в Wayland slot-протоколе `ru.shturman.shell_slot`, не передаёт `wl_surface` по D-Bus — см. c-shell §4), `RequestForeground(slot)`, `ShowOverlay(decl)`.
|
||
- **Сигналы:** `ForegroundChanged(app)`, `NavigatedTo(screen)`, `DistractionModeChanged(level)`.
|
||
- Декларативный вклад = данные (рендерит shell); богатый = Wayland-поверхность.
|
||
|
||
### `ru.shturman.Media` / `…Nav` / `…Phone`
|
||
- Свои интерфейсы (play/pause/route; navigateTo/cancel; dial/answer/hangup). **Детали — в спеках доменов** H/I/G; здесь — только факт регистрации на шине.
|
||
|
||
---
|
||
|
||
## 5. Брокеринг доступа песочных апов (портал-паттерн)
|
||
|
||
1. Манифест плагина декларирует capabilities (`vehicle_read:[speed]`, `network`, `assistant_intents`…).
|
||
2. App-Host поднимает плагин в bubblewrap и даёт ему **фильтрующий D-Bus-прокси**, сконфигурированный под эти capabilities.
|
||
3. Прокси даёт **грубую** изоляцию — сервис/интерфейс/метод/сигнал (payload/аргументы НЕ инспектирует). Пример: `vehicle_read:[speed]` → `VehicleData` (read) **достижим**, а `Power`, чужие апы и write-методы — **нет**. **Тонкую** авторизацию по конкретному имени сигнала / ключу настроек делает сам сервис по идентичности `sender` (см. VehicleData, Settings).
|
||
4. Рантайм-согласия (сеть «сейчас») — через `PermBroker.RequestRuntimeGrant`.
|
||
|
||
Итог: плагин физически не может дотянуться до того, чего нет в манифесте. Детали модели — [security-privacy.md](security-privacy.md).
|
||
|
||
---
|
||
|
||
## 6. Точки расширения через IPC
|
||
|
||
- **Интенты ассистента:** плагин реализует `ru.shturman.IntentHandler1.HandleIntent(intent_id, slots) → result` и регистрируется через `Assistant.RegisterIntents`. Латентно-критичные интенты (громче, домой) ассистент обрабатывает локально без LLM.
|
||
- **Вклад в UI:** плагин зовёт `Shell.RegisterTile/RegisterScreen` (декларативно или поверхностью).
|
||
|
||
Полные контракты SDK (манифест, биндинги, точки расширения) — [plugin-sdk.md](plugin-sdk.md).
|
||
|
||
---
|
||
|
||
## Открытые вопросы (найдено на self-review → роутинг в нужные доки)
|
||
|
||
Не теряем; решается в указанных документах.
|
||
|
||
- ✅ **Гейтинг data-plane, не только D-Bus.** → решено в [security-privacy.md](security-privacy.md) §4
|
||
(PipeWire/Wayland гейтятся capability'ями через bubblewrap-сокеты). API-часть — в plugin-sdk.
|
||
- ✅ **Экспорт объектов из песочницы.** → решено в [security-privacy.md](security-privacy.md) §4
|
||
(плагин OWN под префиксом `ru.shturman.plugin.<id>.*`).
|
||
- ✅ **Приватное хранилище апа.** → решено в [security-privacy.md](security-privacy.md) §4
|
||
(`storage` → mount `/data/apps/<id>/`).
|
||
- ✅ **Коллизия интентов.** → решено в [plugin-sdk.md](plugin-sdk.md) §5 (слоистая
|
||
политика разрешения); тонкости LLM-роутинга — домен D.
|
||
- 🟡 **Целостность манифеста.** Модель доверия — [security-privacy.md](security-privacy.md) §6;
|
||
подпись/стор — задел домена F.
|
||
- ◻️ **Быстрый канал для приборки.** → [architecture.md](../architecture.md) §4 + домен E (**открыто**).
|
||
|
||
---
|
||
|
||
## Журнал решений (ipc)
|
||
|
||
| Решение | Выбор | Дата |
|
||
|---------|-------|------|
|
||
| Топология шины | системная шина устройства + фильтрующий прокси на ап (🟡 на подтверждение) | 2026-06-16 |
|
||
| Изоляция доступа апов | портал-паттерн: per-app dbus-proxy из манифеста | 2026-06-16 |
|
||
| Соглашения имён/версий | `ru.shturman.*`, версия в имени интерфейса; мажоры сосуществуют в окне поддержки (аддитивно) | 2026-06-16 |
|
||
| Enforcement | грубо — прокси (сервис/метод); тонко (per-signal/per-key) — сам сервис по `sender` | 2026-06-16 |
|
||
| Идентичность | только из аутентиф. соединения, не из аргумента; клиент-состояние снимается по `NameOwnerChanged` | 2026-06-16 |
|
||
| Location/GPS | отдельный сервис `ru.shturman.Location` (домен K); GPS-скорость не через E | 2026-06-16 |
|