Initial import: ICE-NET research docs and Rust workspace (v0.4)
Some checks failed
rust-ci / checks (push) Has been cancelled
Some checks failed
rust-ci / checks (push) Has been cancelled
- Rust workspace: 7 library crates, icenetd CLI, icenet-city (Slint GUI) - Sim: fix false Delivered after a route cut, derive traffic class from payload size, per-link airtime slots (link capacity, queueing) - Docs: single docs/STATUS.md for all figures, remove v0.2/egui leftovers, drop unimplemented seed claims, uncheck store-and-forward - License: LGPL-3.0-or-later (LICENSE, LICENSES/GPL-3.0.txt)
This commit is contained in:
commit
2e61688eb3
141 changed files with 13993 additions and 0 deletions
44
docs/architecture/contracts.md
Normal file
44
docs/architecture/contracts.md
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
# Первые контракты и определения
|
||||
|
||||
## Какие ID какие
|
||||
|
||||
- `NodeId` **реальной сети** в `icenet-core` пока представлен `u64` исключительно для каркаса. Это НЕ криптографическая идентичность!
|
||||
- `SimNodeId` по сути тот же тестовый ID. В будущем: стабильный fingerprint публичного ключа и отдельный DeviceID.
|
||||
- `ServiceId(u64)` — логический номер сервиса, не ОС-порт и не гарантия уникальности без схемы namespace.
|
||||
- `LinkKind::{SlowRadio, FastWireless, Wired, Internet}` — профили симуляции, не протоколы передачи по воздуху.
|
||||
|
||||
## Классы
|
||||
|
||||
- `Control`: объявления/короткие служебные данные, минимальный payload.
|
||||
- `Text`: малый payload (≤ 4096 Б), в исключительных случаях допустима передача по slow radio.
|
||||
- `Bulk`: файлы/фото, `SlowRadio` запрещён независимо от скорости маршрута.
|
||||
- Класс **выводится из размера**: `effective_for(bytes)` повышает Control > 256 Б до Text, Text > 4096 Б до
|
||||
Bulk; `Bulk` не уменьшается. Метка отправителя не даёт доступа к slow radio.
|
||||
|
||||
## Маршрут
|
||||
|
||||
- `choose_path` возвращает последовательность NodeId, индексы использованных линков и приблизительную
|
||||
задержку сериализации **без очереди**.
|
||||
- Каждый переход проверяется на `enabled`, разрешённый класс, throughput > 0.
|
||||
- Для сравнимости первые измерения: dijkstra с deterministic tie-break, затем baseline shortest hops.
|
||||
- Нельзя автоматически считать `route_found` равным `delivered`.
|
||||
- Линк несёт одну передачу за раз: время прибытия включает ожидание слота. `Delivered` ставится
|
||||
только если маршрут (узлы, линки, класс) ещё пригоден на момент `tick`.
|
||||
- У сообщения есть `created_ms`/`expires_ms`; истёкшее сообщение переходит в `Expired`
|
||||
и не оживает. Прибытие не позже `expires_ms` считается доставкой.
|
||||
- CSV/JSON экспорт детерминирован и не использует системные часы.
|
||||
|
||||
## Сетевой пакет (черновик)
|
||||
|
||||
`magic | version | class | service_id | payload_len | bytes`.
|
||||
|
||||
- Пример без криптографии, без anti-replay, без fragmentation.
|
||||
- Отдельный парсер ограничивает длину входящих байтов и возвращает `Result`.
|
||||
- В продакшене формат нужно будет изменить после threat modeling и test vectors.
|
||||
|
||||
## Результат безопасности
|
||||
|
||||
- `Permit`, `Deny(reason)`; без "strike back".
|
||||
- `Deny` не расходует replay/rate state; `sequence` фиксируется только после `Permit`.
|
||||
- Входной `authenticated: bool` в scaffold — только тестовый флаг,
|
||||
**не криптографическая проверка**.
|
||||
47
docs/architecture/crates.md
Normal file
47
docs/architecture/crates.md
Normal file
|
|
@ -0,0 +1,47 @@
|
|||
# Cargo workspace: границы крейтов
|
||||
|
||||
| Crate | Ответственность | Кому может зависеть |
|
||||
|---|---|---|
|
||||
| `icenet-core` | типы идентификаторов, класс сообщения, среда | стандартная библиотека |
|
||||
| `icenet-wire` | framing + парсер *чернового* пакета | core |
|
||||
| `icenet-guard` | детерминированные ACL, размер, очередь, replay, rate (без crypto) | core |
|
||||
| `icenet-routing` | выбор допустимого пути на графе, индексы линков | core |
|
||||
| `icenet-transport` | интерфейс отправки байтов, memory + UDP адаптеры | core |
|
||||
| `icenet-sim` | виртуальное время, узлы, ёмкость линков, сценарии, метрики | core, routing |
|
||||
| `icenet-sdk` | будущий публичный фасад API | core, wire, guard, transport |
|
||||
| `icenetd` | CLI и UDP `serve`/`send-udp`; позже daemon | sdk, sim |
|
||||
| `icenet-city` | GUI-карта и контроллер сценариев | sim, core, Slint |
|
||||
|
||||
## Принципы границ
|
||||
|
||||
- Ни один core crate не зависит от `Slint`, Tokio, Linux, Wi-Fi или LoRa.
|
||||
- Sim **не** использует `icenetd`; GUI **не** содержит алгоритма маршрутизации.
|
||||
- SDK является библиотекой встраивания, а daemon и GUI — клиентами публичных интерфейсов.
|
||||
- Адаптеры настоящего радио добавятся **после** тестов в симуляторе и решения ADR.
|
||||
- Защиту и типы не дублировать в GUI: дополнять tests на границе библиотеки.
|
||||
|
||||
## Почему не 20 crates
|
||||
|
||||
SOLID — не повод усложнять сборку. Переносим модуль в crate, если есть отдельная
|
||||
ответственность, тестируемый контракт или платформенная граница. Сейчас есть
|
||||
7 библиотек и 2 приложения, почти все минимальные.
|
||||
|
||||
## Программируемые интерфейсы
|
||||
|
||||
- `Transport::send(bytes)`, `Transport::recv()` — реальные bytes, не UI-события.
|
||||
- `choose_path(nodes, links, source, destination, class, size)` — чистая функция.
|
||||
- `City::send(...)`, `City::tick(delta_ms)`, `City::set_link_enabled(...)`, `City::link_airtime_ms(kind)` — контролируемая модель.
|
||||
- `Guard::check(context)` — решение доступа, не ответная атака.
|
||||
- `icenetd route|send|sim|policy|wire-*` — headless-проверка этих контрактов.
|
||||
|
||||
Детали: [API-контракты](contracts.md) и [симулятор](../simulator/city_editor.md).
|
||||
|
||||
## Зависимости и границы UI
|
||||
|
||||
`icenet-city` — только адаптер интерфейса. Slint UI в `ui/main.slint`;
|
||||
`src/state.rs` изменяет `City`; `src/view.rs` конвертирует данные в модели;
|
||||
`src/main.rs` подключает callbacks. В остальные crates не импортируется Slint.
|
||||
|
||||
Все 7 библиотек намеренно разделены по обязанностям, **все без внешних crates** (числа — в [STATUS](../STATUS.md)).
|
||||
Если эти границы перестанут приносить пользу, нужно объединить crates по ADR,
|
||||
а не бездумно делить ещё мельче. См. [аудит](../build/dependencies.md).
|
||||
48
docs/architecture/decisions.md
Normal file
48
docs/architecture/decisions.md
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
# ADR register
|
||||
|
||||
| ADR | Решение | Статус |
|
||||
|---|---|---|
|
||||
| ADR-001 | Userland Rust вместо Linux kernel fork | Принято для MVP |
|
||||
| ADR-002 | Slow control / fast bulk policy | Принято как **гипотеза** |
|
||||
| ADR-003 | Rust workspace + отдельные integration tests | Принято |
|
||||
| ADR-004 | Город — графовая DES-модель, не RF-доказательство | Принято |
|
||||
| ADR-005 | Slint 1.18.1 + software renderer для native GUI (egui удалён) | Принято в v0.3 |
|
||||
| ADR-006 | Реальная криптография, wire-format, физические драйверы | Открыто |
|
||||
| ADR-007 | Свой полноценный протокол или адаптер к Reticulum | Открыто до экспериментов |
|
||||
| ADR-008 | Общая идентичность человека на нескольких устройствах | Открыто |
|
||||
| ADR-009 | TTL и явное состояние `EXPIRED` для недоставленных сообщений | Принято в v0.3 |
|
||||
| ADR-010 | Лицензия собственного кода: LGPL-3.0-or-later | Принято (автор проекта) |
|
||||
| ADR-011 | Класс трафика выводится из размера, метка не доверена | Принято в v0.4 |
|
||||
| ADR-012 | Ёмкость линка: слоты эфира с владельцем, очередь на ребре | Принято в v0.4 |
|
||||
|
||||
## Для каждого нового ADR
|
||||
|
||||
Описание контекста → альтернативы → причины выбора → проверяемые последствия → риски → срок ревизии.
|
||||
|
||||
Запрещено объявлять открытые ADR реализованными в README.
|
||||
|
||||
## ADR-010 · Лицензия: LGPL-3.0-or-later
|
||||
|
||||
- **Контекст:** автор выбрал LGPL; репозиторий не имел лицензии.
|
||||
- **Решение:** LGPL-3.0-or-later; тексты в `LICENSE` и `LICENSES/GPL-3.0.txt` (LGPL v3 опирается на GPL v3).
|
||||
- **Альтернативы:** LGPL-2.1 (несовместима с GPLv3-only), MIT/Apache (не выбраны автором).
|
||||
- **Последствия:** Rust линкует crates статически; при распространении бинарника с LGPL-кодом нужно
|
||||
дать получателю возможность пересобрать его с изменённой библиотекой (исходники или объектные файлы).
|
||||
Комбинация с Slint по GPLv3 даёт GPLv3 для бинарника GUI. Юристом не проверялось.
|
||||
- **Ревизия:** до первой публикации бинарников.
|
||||
|
||||
## ADR-011 · Класс по размеру
|
||||
|
||||
- **Контекст:** метка `Text` на 5 МБ проходила по slow radio: класс заявлял отправитель.
|
||||
- **Решение:** `TrafficClass::effective_for(bytes)`: Control > 256 Б → Text, Text > 4096 Б → Bulk;
|
||||
`Bulk` не уменьшается. Применяется внутри `choose_path`, поэтому защищает всех вызывающих.
|
||||
- **Последствия:** лимит Text совпадает с лимитом payload wire-кадра; пороги условные, их надо
|
||||
подтвердить airtime-расчётом для реального радио (ADR-006).
|
||||
|
||||
## ADR-012 · Ёмкость линка
|
||||
|
||||
- **Контекст:** линк пропускал любое число сообщений параллельно, поэтому S4/H2/H4 были пустыми.
|
||||
- **Решение:** на каждом линке календарь слотов; слот принадлежит сообщению; перепланирование
|
||||
освобождает ещё не начатые слоты. Время передачи — `transfer_ms + HOP_OVERHEAD_MS` на hop.
|
||||
- **Последствия:** задержка растёт с очередью, TTL может истечь из-за бэклога. Выбор пути пока не
|
||||
учитывает бэклог, перепланирование начинает с источника — это записано как ограничение.
|
||||
44
docs/architecture/overview.md
Normal file
44
docs/architecture/overview.md
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
# Актуальная архитектура ICE-NET
|
||||
|
||||
## Инварианты
|
||||
|
||||
1. `NodeID` — стабильная криптографическая идентичность (будущая), не IP и не физическая координата.
|
||||
2. `ServiceID` адресует сервис на узле; 64-битные значения — концепция, **не TCP-порты**.
|
||||
3. Медленный канал (`SlowRadio`) допускает beacon, route-discovery и маленький текст, но не bulk.
|
||||
Класс определяется **размером**, а не только меткой отправителя (Control ≤ 256 Б, Text ≤ 4096 Б).
|
||||
4. Фото и файлы отправляются только если найден **разрешённый по политике** путь.
|
||||
5. Отсутствие пути ≠ успешная доставка; статусы `Queued`, `InFlight`, `Delivered`, `Expired` различаются; `Delivered` только если маршрут жив.
|
||||
6. End-to-end криптография обязательна для реальной сети, **в симуляторе пока не реализована**.
|
||||
7. Сетевой слой существует независимо от транспорта (UDP/радиомодем/ethernet) и UI.
|
||||
|
||||
## Границы
|
||||
|
||||
```text
|
||||
apps/icenet-city ───> icenet-sim ──> icenet-routing ──> icenet-core
|
||||
apps/icenetd ───────> icenet-sim (offline-команды)
|
||||
apps/icenetd ───────> icenet-sdk ───> icenet-wire / icenet-transport / icenet-guard
|
||||
└──────────────> icenet-core
|
||||
```
|
||||
|
||||
Актуальный список и точные зависимости: [crates.md](crates.md).
|
||||
|
||||
## Control plane / data plane
|
||||
|
||||
- **Control**: маленькие объявления, отметки доступности, поиск маршрутов, ACK; отдельный лимит airtime и TTL.
|
||||
- **Data**: текст, файлы, сервисные потоки; расписание маршрутов с учётом профиля физического канала.
|
||||
- В будущем LoRa может передавать экстренный текст, если это допускают местные правила.
|
||||
- В сети неизвестных узлов объявления не должны бесконтрольно распространяться; нужны квоты, дедупликация, expire.
|
||||
|
||||
## Какую проблему изучаем
|
||||
|
||||
Не «мы изобрели mesh/IPv6/крипто-адреса», а:
|
||||
**может ли строгая политика передачи по гетерогенным каналам избежать перегрузки узкой полосы,
|
||||
сохранив доставку коротких сообщений и стабильную идентичность?**
|
||||
|
||||
Это гипотеза. Сравнивать надо с [Reticulum](../research/reticulum.md) и baselines.
|
||||
|
||||
## Важная разница между симуляцией и продакшеном
|
||||
|
||||
- Редактор города — модель графа со скоростью ребра, не радиотехнический расчёт покрытия.
|
||||
- В нём нет настоящей криптографии, реального Wi-Fi, скрытых терминалов, интерференции, MAC.
|
||||
- Числа в демо условны. Линк несёт одну передачу за раз, но потерь, коллизий и MAC нет. Для реального RF потребуется измерение или ns-3/другая PHY-модель.
|
||||
Loading…
Add table
Add a link
Reference in a new issue