# armdb: интеграция с armour (feature `armour`)
## Обзор
Feature `armour` добавляет интеграцию armdb с экосистемой armour:
- **Db** — менеджер именованных коллекций с метаданными и генерацией ID
- **TreeMeta** — описание коллекции (имя, тип ключа, тип значения, версия)
- **Миграции** — автоматическое применение миграций при открытии дерева
- **RPC-сервер** — TCP/UDS сервер с бинарным протоколом armour-rpc
## Зависимости
### Feature `armour`
```toml
armour = [
"dep:serde", # DbInfo serialization
"dep:serde_json", # Persist format
"dep:rend", # rkyv portable endian types
"dep:arrayvec", # stack-allocated collections
"typed-tree", # TypedTree/TypedMap (Codec)
]
```
### Feature `rpc` (implies `armour`)
```toml
rpc = [
"armour",
"dep:armour-rpc", # протокол и клиент
"armour-rpc/schema", # schema introspection
"dep:compio", # async runtime (io_uring / kqueue)
"dep:futures-util", # Stream/Sink utilities
"dep:async-broadcast", # shutdown broadcast
"dep:ctrlc", # Ctrl-C handler
]
```
## Db
Менеджер базы данных — управляет директорией, метаданными коллекций и генерацией
последовательных ID.
```rust,ignore
use armdb::armour::Db;
let db = Db::open("data/myapp")?;
// Генерация ID для коллекции
let id = db.next_id("users")?; // 1, 2, 3, ...
// Путь для дерева
let path = db.tree_path("users", 1); // "data/myapp/users:v1"
db.close()?;
```
### Структура директории
```text
data/myapp/
db.info # JSON — метаданные коллекций (Persist<DbInfo>)
__seq/ # ConstTree<[u8;8], 8> — счётчики последовательностей
users:v1/ # данные коллекции "users" версии 1
posts:v2/ # данные коллекции "posts" версии 2
```
### DbInfo / CollectionInfo
```rust,ignore
// Персистентные метаданные — версия и хеш типа для каждой коллекции
struct DbInfo {
collections: BTreeMap<String, CollectionInfo>,
}
struct CollectionInfo {
version: u16, // текущая версия схемы
typ_hash: u64, // Typ::h() — хеш типа значения
}
```
## TreeMeta и CollectionMeta
`TreeMeta` — статическое описание коллекции. Используется при открытии дерева.
Можно создать вручную:
```rust,ignore
use armour_core::{KeyScheme, KeyType, Typ};
use armdb::armour::TreeMeta;
const USERS_META: TreeMeta = TreeMeta {
name: "users",
key_scheme: KeyScheme::Typed(&[KeyType::Fuid]),
ty: <User as GetType>::TYPE,
group_bits: 10,
version: 2,
};
```
Или через трейт `CollectionMeta` — тип описывает свою коллекцию:
```rust,ignore
use armdb::armour::{CollectionMeta, TreeMeta};
use armour_core::{GetType, KeyScheme, KeyType};
#[derive(GetType, Rapira)]
struct User {
name: String,
email: String,
}
impl CollectionMeta for User {
const NAME: &'static str = "users";
const VERSION: u16 = 2;
const KEY_SCHEME: KeyScheme = KeyScheme::Typed(&[KeyType::Fuid]);
const GROUP_BITS: u32 = 10;
}
// Typ берётся из GetType автоматически
const USERS_META: TreeMeta = TreeMeta::of::<User>();
```
## Миграции
### TypedTree
```rust,ignore
use armdb::armour::{Db, TypedMigration};
use armdb::{Config, MigrateAction, NoHook, RapiraCodec};
// Функция миграции: вызывается для каждой записи при смене версии
fn migrate_v1_to_v2(key: &[u8; 16], val: &User) -> MigrateAction<User> {
MigrateAction::Update(User { /* ... */ })
}
let migrations: &[TypedMigration<[u8; 16], User>] = &[
(1, migrate_v1_to_v2), // from_version=1 -> текущая версия
];
let tree = db.open_typed_tree::<User, RapiraCodec, NoHook>(
Config::balanced().build(),
NoHook,
migrations,
)?;
```
### ZeroTree
```rust,ignore
use armdb::{Config, NoHook};
let tree = db.open_zero_tree::<Session, { size_of::<Session>() }, NoHook>(
Config::balanced().build(),
NoHook,
&[], // migrations
)?;
```
### Логика миграции
1. Читается `CollectionInfo` из `db.info` для имени коллекции
2. Если `stored.version != meta.version`:
- Ищется миграция с `from_version == stored.version`
- Вызывается `tree.migrate(migration_fn)`
- Для каждой записи callback возвращает `Keep`, `Update(T)` или `Delete`
3. Обновляется `CollectionInfo` (version + typ_hash) в `db.info`
## Read-only Inspector
`Db::inspector()` возвращает заимствованный in-process диагностический API поверх
каждой коллекции, открытой через этот `Db`. Inspector **не требует** feature `rpc`,
не использует `armour-rpc` и **не изменяет** сетевой RPC-сервер. Документация RPC
ниже остаётся отдельной.
Приложение, которое уже владеет `Db`, может:
- обнаруживать зарегистрированные коллекции (`collections()`);
- читать схему, `StorageClass`, возможности сканирования и направление итерации;
- выполнять точный lookup по ключу, счётчики и ограниченные сканы.
Аутентификация, авторизация, редактирование секретов, JSON-сериализация и audit
logging остаются ответственностью приложения — Inspector возвращает только сырые
байты и метаданные armdb.
### Открытие и границы
```rust,ignore
use armdb::armour::{Db, Inspector, CountMode};
let db = Db::open("data/myapp")?;
// ... open_typed_tree / open_zero_map / ...
let inspector = db.inspector();
let collections = inspector.collections()?;
```
- Inspector привязан к lifetime `Db` и не переживает его.
- Мутаций на `Inspector` нет; внутренние handler-реестры недоступны снаружи.
- Видны только коллекции, открытые через `Db`; напрямую открытые `TypedTree` /
`ConstTree` и т.п. не регистрируются.
### Discovery и метаданные
`collections()` возвращает отсортированный по имени список `InspectionCollection`:
| `schema.version` | версия схемы коллекции |
| `schema.typ` | `Typ` для динамического декодирования |
| `schema.key_scheme` / `key_size` | схема и размер ключа в байтах |
| `schema.encoding` | как интерпретировать value-байты (см. ниже) |
| `storage` | `StorageClass` (ValueModel, CollectionShape, StorageBackend) |
| `count` | дешёвый O(1) счётчик live-ключей, если есть; иначе `None` |
| `scan` | `Ordered`, `UnorderedSnapshot` или `ExactOnly` |
| `direction` | `Ascending` / `Descending` для ordered-коллекций |
### Кодировка значений (`InspectionEncoding`)
| `Rapira` | Typed/Var с `RapiraCodec`, или Zero на little-endian когда `typ_fixed_width(Typ) == V` | generic `DynValue` по `Typ` |
| `RawLayout` | Typed/Var с `ZerocopyCodec`/`BytemuckCodec`/`BytemuckSliceCodec`; Zero при несовместимости width/shape/endian | сырой memory image; без обещания DynValue |
| `Opaque` | кастомный `Codec` без контракта | generic-декодер не объявлен |
Ключи не входят в контракт DynValue — Inspector возвращает их как сырые байты.
`GetType` должен описывать ту же последовательность полей и ширины, что и
memory layout. Несовпадения ширины (например `usize` описан как `U32`)
детектируются и остаются `RawLayout`. Same-width семантические ошибки в
описании типа (например big-endian байты `Fuid` описаны как little-endian
`u64`) Inspector не детектирует.
### Операции чтения
**Точный lookup** — `get(name, key)`: валидирует длину ключа; `Ok(None)` для
отсутствующего ключа; `InvalidKey` для неверной длины.
**Счётчики**:
- `CountMode::Current` — O(1) счётчик из метаданных (если handler его публикует);
- `CountMode::Exact` — строгий key-only подсчёт live-ключей без декодирования
значений; ошибки Var/LSM пробрасываются, частичный результат не возвращается.
**Ordered scan** — `range` / `prefix` для коллекций с `ScanCapability::Ordered`.
Используется байтовый порядок коллекции и её направление (`reversed` → `Descending`).
Пагинация: `limit` записей + честный `next_key` (lookahead на одну строку) — ключ
устанавливается только если есть следующая страница. Передайте `next_key` как `after`
для продолжения в том же направлении. Страницы **не** являются point-in-time
снимком через шарды.
**Unordered snapshot** — `snapshot_unordered` для Map без `iterable(true)`:
обход в неопределённом per-shard порядке, не глобальный снимок.
### Map iterability
Решение принимается при открытии Map:
- `iterable(true)` → ordered `range` / `prefix` (`ScanCapability::Ordered`);
- без iterability → только `snapshot_unordered` (`UnorderedSnapshot`).
### Отличие от RPC
| Транспорт | in-process, заимствованный | TCP / UDS |
| Мутации | нет | write, remove, batch, … |
| Зависимости | только `armour` | `armour-rpc`, compio, … |
| Ошибки | `InspectionError` | wire status + `DbError` |
## RPC-сервер
Бинарный протокол поверх length-delimited framing. Поддерживает TCP и Unix Domain Sockets.
### Запуск
```rust,ignore
use armdb::armour::Db;
use armdb::{Config, NoHook, RapiraCodec};
let db = Db::open("data/myapp")?;
// open_typed_tree auto-registers RPC handler when `rpc` feature is enabled
let tree = db.open_typed_tree::<User, RapiraCodec, NoHook>(
Config::balanced().build(),
NoHook,
&[], // migrations
)?;
// Start TCP and/or Unix socket listener
db.listen_tcp("127.0.0.1:9000");
db.listen_uds("/tmp/myapp.sock");
```
### RpcHandler trait
```rust,ignore
pub trait RpcHandler: Send + Sync {
fn name(&self) -> &str;
fn info(&self) -> (u64, u16); // (typ_hash, version)
fn schema(&self) -> armour_rpc::SchemaResponse;
fn scannable(&self) -> bool { false }
fn get(&self, key: &[u8]) -> DbResult<Option<ValueBytes>>;
fn contains(&self, key: &[u8]) -> DbResult<bool>;
fn entry_len(&self, key: &[u8]) -> DbResult<Option<u32>>;
fn first(&self) -> DbResult<Option<(KeyBytes, ValueBytes)>>;
fn last(&self) -> DbResult<Option<(KeyBytes, ValueBytes)>>;
fn range(
&self,
start: Bound<KeyBytes>,
end: Bound<KeyBytes>,
limit: u32,
) -> DbResult<Vec<(KeyBytes, ValueBytes)>>;
fn range_keys(
&self,
start: Bound<KeyBytes>,
end: Bound<KeyBytes>,
limit: u32,
) -> DbResult<Vec<ValueBytes>>;
fn write(&self, key: WriteKey, flag: Option<bool>, value: ValueBytes)
-> DbResult<ValueBytes>;
fn remove(&self, key: &[u8], soft: bool) -> DbResult<()>;
fn take(&self, key: &[u8], soft: bool) -> DbResult<Option<ValueBytes>>;
fn count(&self, exact: bool) -> DbResult<u64>;
fn apply_batch(&self, items: Vec<(KeyBytes, Option<ValueBytes>)>) -> DbResult<()>;
}
```
`scannable()` сообщает клиенту, поддерживает ли коллекция `First`/`Last`/`Range`/`RangeKeys`.
По умолчанию `false`, чтобы `ListCollections` не рекламировал сканирование без реализации.
### Adapter
Единственная реализация `RpcHandler` (и `InspectionHandler`) на все семейства
коллекций — `Adapter<S, W>` (`armdb/src/access/adapter.rs`). `S: Access` даёт
типобезопасный доступ к конкретной коллекции (`TypedTree`, `TypedMap`,
`ZeroTree`/`ZeroMap` для обоих backend'ов, `VarTypedTree`/`VarTypedMap`,
`LsmTree`), `W: Wire` — кодирование значения в/из проводного формата. `Db`
создаёт и регистрирует `Adapter` автоматически при каждом `open_*`, поэтому
ручных обработчиков для встроенных семейств больше нет:
- **get/contains** — `K::from_bytes(key)` -> `Access::with_value`/`Access::contains` -> `Wire::encode`
- **write** — `Wire::decode(value)` -> `Access::put` / условный `Access::atomic_at` для `flag`
- **write с `WriteKey::Sequence`** — генерирует ID через `seq_tree`
- **write с `flag`** — `Some(true)` = только update, `Some(false)` = только insert; precondition через `HeldOps::try_contains` (existence-only: undecodable row → `KeyExists`/`KeyNotFound`, не corruption). Collection `upsert` по-прежнему декодирует значение.
- **range/first/last** — `Access::scan_range`/`with_first`/`with_last`; для Map требует `iterable(true)`, иначе `NotImplemented`
- **scannable** — `true`, когда `Access::scan_capability() == ScanCapability::Ordered`
- **apply_batch** — серия put/delete в цикле (не атомарна)
`RpcHandler` остаётся публичным трейтом — коллекция, открытая не через `Db`
(или нестандартное хранилище), по-прежнему может реализовать его вручную;
см. «Пользовательские RpcHandler» ниже.
### Протокол
Каждый запрос: `opcode(u8) + hashname(u64) + payload`. Ответ: `status(u8) + payload`.
| Get | Получить значение по ключу |
| Contains | Проверить наличие (возвращает длину значения) |
| First / Last | Первый / последний элемент |
| Range / RangeKeys | Диапазонный запрос (ключи+значения / только ключи) |
| Count | Количество элементов |
| Write | Вставка/обновление с опциональным флагом |
| Remove | Удаление |
| ApplyBatch | Пакетная операция |
| ListCollections | Список всех коллекций с метаданными |
### Shutdown
Ctrl-C отправляет broadcast через `async_broadcast`. Все accept-loop'ы и активные
соединения завершаются. `listen_tcp`/`listen_uds` запускают compio runtime в отдельном
потоке.
### Trust model
RPC-сервер рассчитан на **доверенную сеть**: пиры не аутентифицируются, операции не
авторизуются. `Range` и `RangeKeys` материализуют ответ в памяти. `limit == 0` ограничивается
`UNLIMITED_RANGE_CAP`; явный больший ненулевой `limit` соблюдается. `Count { exact: true }` по-прежнему
может сканировать всю коллекцию. Держите RPC listener на loopback/UDS или за аутентифицированным
туннелем; не выставляйте листенер на недоверенную сеть. Полное описание (включая репликацию) —
раздел «Network trust model» в `design.md`.
## Пользовательские RpcHandler
`Adapter` покрывает все типизированные семейства: `TypedTree`/`TypedMap`,
`ZeroTree`/`ZeroMap` (оба backend'а), `VarTypedTree`/`VarTypedMap`, `LsmTree` —
`Db::open_*` регистрирует его сам. Для нетипизированных коллекций (`ConstTree`,
`ConstMap`, `VarTree`, `VarMap` — без `CollectionMeta`-значения) `RpcHandler`
по-прежнему нужно реализовать вручную.
Scan-capable handler **обязан** переопределить `scannable()` → `true` и реализовать все четыре
метода сканирования (`first`, `last`, `range`, `range_keys`). Дефолт `scannable() == false`
предотвращает ложноположительное обнаружение в `ListCollections`.
```rust,ignore
struct MyConstHandler {
tree: Arc<ConstTree<[u8; 16], 64>>,
}
impl RpcHandler for MyConstHandler {
fn name(&self) -> &str { "my_const" }
fn scannable(&self) -> bool { true }
fn get(&self, key: &[u8]) -> DbResult<Option<Vec<u8>>> {
let k: [u8; 16] = key.try_into().map_err(|_| DbError::KeyNotFound)?;
Ok(self.tree.get(&k).map(|v| v.to_vec()))
}
// ... first, last, range, range_keys и остальные методы
}
```