che-rest 0.4.0

Typed REST framework and project tooling for che-orm applications
Documentation
# Объектная синхронизация: протокол 3

`ObjectSyncEndpoints` — явно подключаемый режим для объектов с прямыми и
групповыми ACL. Сервер хранит один UUID, одну запись и общую ревизию для всех
пользователей. Протоколы 1 и 2 сохраняют прежние маршруты, форматы и семантику;
новый режим не включается автоматически.

## Подключение

Модель использует UUID, `SyncModel` и `AccessModel`, как в `docs/access.md`.
ViewSet объявляет `type Permission = Access<Model>` и устанавливает
`config.extend(ObjectSyncEndpoints::new(self.clone()))`. В `SyncViewSet`
возвращается серверный реестр этой модели. Создание требует модельного `add`,
права создателя задаются явно через `CREATOR_PERMISSIONS` и фиксируются в той же
транзакции, что запись, ревизия и журнал.

Установите `che_rest::sync::object_schema_module()` рядом с auth и модулем
приложения. Он объявляет инфраструктурную схему с постоянным владельцем
`che_object_sync`, чтобы последующие `makemigrations` сохраняли таблицы доставки.
Это чистое объявление, без DDL и запуска фоновых задач.

Для клиента нужен `ModelLogClient::open_objects(db, registry, server, account)` и
`sync_http::RestObjectTransport`. `RestResource` использует серверный ORM
сериализатор, как в протоколе 2. В Tauri доступны
`TauriSync::open_objects` и модуль схемы `che_tauri::ObjectSyncSchema`.
Идентичность сервера и аккаунта задаётся доверенным приложением. Обновление
токена того же аккаунта не меняет владение БД и не удаляет outbox.

## Схема и явный переход

Сначала сохраните `che_sync::object_log::migration_operations(Server/Client)`
в **новой compiled migration**, затем примените её обычным `migrate`. Старые
миграции, UUID, ревизии, журналы, receipts и replica ID не переписываются.
Открытие клиента, построение сервера и запрос страницы не создают таблицы.
Готовые замороженные follow-up миграции есть в Todo-примере.

Для свежей клиентской БД достаточно `open_objects`. БД протокола 2 этим методом
не открывается. Явный `ModelLogClient::upgrade_to_objects`:

1. Требует уже применённой follow-up миграции.
2. Отклоняет переход при наличии отправленной операции: сначала завершите её
   исходным транспортом и протоколом. Сохранённый payload не перекодируется.
3. Атомарно меняет маркер протокола и привязывает БД к серверу/аккаунту.
4. Сохраняет локальные строки, shadow, черновики и старые курсоры. Ранее
   подтверждённые строки скрываются до новой выдачи доступа; одного `add`
   недостаточно для отправки старых правок этих строк.
5. Начинает новую адресную ленту с нуля. Первое разрешённое состояние содержит
   полный объект; старые diff для его восстановления не нужны.

Старая whole-model БД сервера может использоваться после явного применения
миграции и назначения ACL существующим объектам. Как и раньше, незаписанные
в модельный журнал данные требуют отдельного `backfill_model_log`; startup и
GET/POST доставки не выполняют backfill.

## Контракт HTTP

Запись использует обычные POST/PATCH/PUT/DELETE маршруты сериализатора.
Условный запрос передаёт `X-Sync-Protocol: 3`, `X-Sync-Replica`,
`Idempotency-Key`, `If-Match`, `X-Sync-Version`, а при создании — `X-Sync-Entity`.
Тело, путь и идентификаторы сохраняются один раз. Пространство payload
транспорта — `che-rest.object.v3`, отдельно от `che-rest.model.v2`.

Чтение ленты: `POST /api/<resource>/sync/objects/`:

```json
{"protocol_version": 3, "cursor": null, "limit": 100}
```

В следующих запросах передаётся весь полученный `cursor`:
`{model, history, feed, sequence}`. `sequence`, ревизии и все i64 в протоколе
передаются десятичными строками. `feed` — непрозрачный постоянный UUID,
привязанный к аутентифицированному principal, модели и серверному пути проекции.
Два queryset одной модели на разных маршрутах имеют независимые ленты. Чужой курсор,
неизвестная история, отрицательная/будущая граница или неверная версия
отклоняются. Поле `after` ответа должно совпасть с локальной границей, события
идут подряд; состояние и курсор применяются атомарно.

Ответ содержит `events`, `can_create`, `cursor`, `has_more`:

| Событие | Содержимое | Применение |
| --- | --- | --- |
| `state` | Полное текущее `ModelState`, `rights: {read, change, delete}` | Выдача, изменение данных или изменение доступных действий |
| `revoked` | Только `record_id` | Скрыть активную проекцию; сохранить локальные правки отдельно |
| `deleted` | `record_id`, ревизия | Отдельное состояние серверного удаления |

Ответ записи имеет `Content-Type: application/vnd.che-sync.v3+json` и один из
вариантов: `canonical` с обычным `ModelWriteResult` либо `acknowledged` с
`operation_id` и исходом `accepted/conflict/rejected`, без состояния объекта.
Коды — 201 для принятого создания, 200 для остальных принятых записей, 412 для
конфликта, 400 для окончательного отклонения. Ошибка транспорта/авторизации без
канонического подтверждения остаётся неизвестным исходом и требует повтора.

Receipts неизменяемы. Сервер сначала находит исход уже выполненной операции,
а перед раскрытием её содержимого проверяет **текущие** права чтения каждого
объекта. После отзыва чтения повтор может подтвердить принятую запись, но не
возвращает сохранённые в receipt бизнес-поля. Если сохранённое состояние уже
отличается от текущего, сервер также подтверждает только исход операции: новая
выдача чтения не раскрывает исторические поля из receipt. После такого ответа
клиент повторно проходит адресную ленту, чтобы получить актуальные права и данные.
Обнуляется только позиция доставки: привязка к `history` и `feed` сохраняется,
поэтому смена серверной истории по-прежнему отклоняется.
Проверка права записи выполняется снова для каждой новой операции, включая no-op, внутри committing transaction.

## Доставка и транзакционные границы

Реализация использует синхронную сверку текущей видимости с сохранённой лентой,
без фонового раскрытия групп. В serializable transaction сервер блокирует строки
модельного журнала, читает текущие объекты и ACL, фиксирует изменения видимости
и номера событий, затем формирует страницу. Данные и ACL изменяются через свои
транзакционные сервисы; откат не оставляет частично изменённую видимость.
События доставки хранят UUID и порядок, **не копию бизнес-полей**.

Даже при повторе старой страницы сервер повторно проверяет текущие права:
старое событие выдачи превращается в отзыв, если чтение уже запрещено, либо
передаёт текущее полное состояние. Нельзя получить исторические поля из старой
страницы. Сохранённое наблюдение видимости переживает рестарты; клиент, ещё не
увидевший отзыв, не зависит от наличия новых бизнес-правок.

Лента отражает актуальную проекцию, а не аудит каждого промежуточного перехода:
выдача и отзыв между двумя сверками могут схлопнуться до текущего состояния.
Аудит ACL сохраняется отдельно в `AccessEvent`. Полный проход обнаруживает также
изменение видимости из SQL-фильтра queryset; нельзя заменять его обычной
фильтрацией diff-журнала протокола 2.

**Стоимость:** каждый запрос сканирует всю модель и ранее известные объекты,
загружает их идентификаторы и проверяет ACL. Лимит ограничивает размер ответа,
а не объём сверки. На это время удерживаются блокировки журнала. Этот режим
подходит для ограниченных моделей; адресная фоновая очередь, индексация
получателей и очистка старых событий пока не реализованы. Курсоры не имеют
скрытого срока истечения, история автоматически не обрезается.

## Офлайн-правки и интерфейс

При отзыве чтения физическая локальная строка и shadow сохраняются, но ORM
runtime скрывает строку в выборках, counts, joins и вложенных SELECT. Новые
локальные записи в этот объект и подготовка новых отправок блокируются.
Raw SQL и исходный незащищённый handle — доверенный доступ приложения к данным
устройства, как и в остальных sync-режимах.

Уже отправленный запрос продолжает повторяться с прежним payload и identity.
Событие отзыва может скрыть строку, пока этот исход неизвестен. Состояния объектов
с ожидающими запросами сохраняются отдельно и переживают перезапуск; их shadow
остаётся замороженным до подтверждения запроса. Курсор продолжает продвигаться,
поэтому последующие страницы, включая отзывы на другие объекты, доступны сразу.
Отзыв удаляет отложенное состояние соответствующего объекта. Если пришло
подтверждение без данных, запрос считается завершённым; черновик и локальная
база для слияния сохраняются со статусом `review`. Для исхода `accepted` клиент
также сохраняет отправленное намерение, восстановленное из неизменяемого запроса
и его базы. Свежая выдача использует его как базу слияния, чтобы уже принятые
поля не считались повторной локальной правкой; последующие локальные изменения
сохраняются, а реальные конфликты требуют разрешения. Если черновика больше нет,
объект возвращается в `active`. При повторной выдаче чтения
черновик не отправляется автоматически: сначала получите свежую страницу,
разрешите конфликт при наличии и явно вызовите `resume_object`.

Публичные клиентские методы и команды `che_model_sync`:

- `object_status` / `object_access`: права, `active/revoked/deleted/review/discarded`,
  наличие отличающегося черновика и отправленного запроса.
- `retained_draft`: явный просмотр/экспорт локальной копии, включая скрытую.
- `resume_object`: пользователь подтвердил отправку после восстановления прав.
  Для удаления проверяются `read + delete`, для изменения — `read + change`.
- `discard_retained_draft`: явное удаление скрытой локальной копии. Недоступно,
  пока существует отправленный запрос с неизвестным исходом.

`blocked` может означать сохранённые правки без доступа, а не только конфликт
полей. UI должен показать причину и не запускать бесконечные повторы. Серверный
запрет действует сразу; отключённое устройство узнаёт об отзыве только при
связи с сервером. Политику удержания локальных копий определяет приложение.

## Поддерживаемые схемы

Сейчас поддержаны `Access<Model>`, scalar SQL queryset без JOIN/LIMIT/OFFSET,
прямые и групповые grants, модельные права в явно выбранном режиме и полный
набор scalar sync-полей, объявленных в сериализаторе. Скрытое от сериализатора
бизнес-поле нельзя незаметно раскрыть через sync: регистрация отклоняется.

FK-модели, nested serializers, наследование доступа по связям, broad CRUD
signals и прямые image CAS actions отклоняются. Для них нужны отдельные
контракты проекций/получателей. Адресные WebSocket-сигналы и фоновый fan-out
остаются следующим этапом. Нельзя одновременно устанавливать разные sync
extensions или image mutation endpoints на один ViewSet.

## Проверка

`tests/object_sync.rs` проверяет REST, ACL, общие ревизии, группы, пагинацию,
receipt replay и явный upgrade. `che-sync/tests/object_log.rs` выполняет один
контракт SQLite/PostgreSQL, включая сохранение черновика после отзыва.
`../che-tauri/examples/todo-sync/server/tests/shared_objects.rs` проверяет
реальный HTTP, Tauri-клиентов двух аккаунтов, повторные compiled migrations и
соответствие frozen истории желаемой схеме. Команды запуска shared Todo — в его
README. Прежние сценарии whole-model синхронизации сохранены.