ADR Ф8-1: облако-lite — WebDAV, Яндекс.Диск, Nextcloud (выпуск 1.3)
Статус: предложено, 15.10.2026 (сессия
проектирования 1.x, ветка claude/design-f6-f8-2d6dbf).
Берётся в работу после беты 0.9; по плану 15.10 фаза 8 —
5.04–30.07.2027, бюджет облака 20–30 сд. Основание: план
plan/report-20261015/ (фаза 8, аудит 05 задача 7, макет
mocks/07-cloud-conflict.html в ветке
claude/upload-latest-project-version-c3c4be), ADR сетевого
слоя S1 docs/development/adr-network-layer.md (ветка
claude/release-beta09-17edde), решение № 40.
Предполагается, что владелец к 23.10 выберет вариант А сетевого слоя
(HTTPS средствами ОС); от этого выбора облако не зависит — оно работает
поверх трейта Transport.
Задача
Открыть и сохранить документ в общей папке без своего сервера: «общая папка отдела» на Яндекс.Диске, Nextcloud организации или любом WebDAV (в т. ч. «МойОфис Частное облако», Р7-Диск, OwnCloud, Synology — у всех есть WebDAV).
- Подключить хранилище в Hub (раздел «Облако»): адрес и вход; учётные данные — в связке ключей ОС.
- Обзор и открыть: список папок, значки «синхронизирован / изменён другим / только на этом компьютере / ждёт отправки» (макет 07).
- Сохранить с проверкой ревизии: если на сервере новее — честный конфликт, ничего не перезаписывается молча.
- Офлайн: без сети работа продолжается, сохранения копятся в очереди и уходят при подключении.
Не входит: совместная правка в реальном времени и присутствие (фаза 12 «облако MOffice», CRDT/Yrs), синхронизация всей папки в фоне (как клиент Диска), общий доступ и права (делаются в веб-интерфейсе хранилища).
Что есть и чего не хватает
meridian-net(S1, веткаclaude/release-beta09-17edde): трейтTransportумеет только GET с пределом размера, таймаутом и прокси; ответ — тело, статус кроме 200 — ошибка. Для WebDAV нужно: методыPROPFIND, GET, PUT, MKCOL, MOVE, DELETE(иLOCK/UNLOCK— опционально), заголовки запроса (Authorization,If-Match,If-None-Match,Depth,Content-Type), тело запроса потоком (файл), статус и заголовки ответа (ETag,Last-Modified,Location), коды 201/204/207/404/412/423/507. → Расширение трейта — первая задача (C1), в крейте S1.- Защита при локальном сохранении уже есть:
kernel/crates/meridian-ffi/src/saved_file.rsхранит хеш прочитанной версии и даётMERIDIAN_E_CONFLICT, конфликт → копия. Облако повторяет тот же принцип: «прочитанная ревизия» =ETagсервера. - D-Bus-клиент своим кодом —
ui/meridian-platform/src/dbus.rs(для AT-SPI): годится для Secret Service на Linux. - Сравнение абзацев для диалога конфликта — нужно в Write (рецензирование, фаза 9 «Сравнить»); для 1.3 — упрощённое сравнение по абзацам (LCS по хешам абзацев), как в макете.
Протоколы и варианты
| Вариант | Как | За | Против |
|---|---|---|---|
| А. Один клиент WebDAV (RFC 4918) + адаптер Яндекс.Диска по REST API (рекомендую) | WebDAV для Nextcloud и «любого сервера»; Яндекс.Диск — REST
cloud-api.yandex.net/v1/disk (OAuth, ссылки на
загрузку/выгрузку,
md5/sha256/revision в
метаданных) |
у Яндекса WebDAV для сторонних программ ограничен по скорости и
требует пароля приложения — REST надёжнее; оба адаптера за одним трейтом
CloudStore |
два адаптера; REST Яндекса может меняться (риск плана) |
Б. Только WebDAV для всех, включая
webdav.yandex.ru |
один протокол | минимум кода | ограничение скорости и стабильности WebDAV Яндекса для сторонних клиентов; вход только паролем приложения |
В. Библиотеки (OpenDAL, rclone процессом — как в
00-foundation.md §11) |
готовые адаптеры к десяткам облаков | быстро | нарушает № 40; rclone — внешняя программа 50+ МБ |
Решение — А. Трейт и общий код (очередь, конфликт, кэш) один; адаптеры:
pub trait CloudStore: Send + Sync {
fn list(&self, dir: &RemotePath) -> Result<Vec<Entry>, CloudError>; // имя, размер, ревизия, время, автор*
fn stat(&self, path: &RemotePath) -> Result<Option<Entry>, CloudError>;
fn get(&self, path: &RemotePath, sink: &mut dyn Write, p: &mut ProgressFn) -> Result<Revision, CloudError>;
/// Записать, только если на сервере ревизия `expect` (None — файла быть не должно). Конфликт — `CloudError::Conflict(текущая)`.
fn put(&self, path: &RemotePath, src: &mut dyn Read, len: u64, expect: Option<&Revision>) -> Result<Revision, CloudError>;
fn mkdir(&self, path: &RemotePath) -> Result<(), CloudError>;
fn rename(&self, from: &RemotePath, to: &RemotePath, overwrite: bool) -> Result<(), CloudError>;
}- WebDAV (
WebDavStore):PROPFIND Depth: 1(свой разбор XML —meridian-xml),GET→ETag;PUTсIf-Match: "<etag>"(илиIf-None-Match: *для нового) → 412 = конфликт. Если сервер не отдаётETag(редко) — сравнениеgetlastmodified+getcontentlengthпередPUTи предупреждение «сервер не поддерживает защиту от перезаписи» в свойствах подключения. Nextcloud: адресhttps://host/remote.php/dav/files/<user>/, автор последнего изменения — свойствоoc:owner-display-name/nc:…если есть (в макете «Иванова И. сохранила в 12:01»). - Яндекс.Диск (
YandexDiskStore): OAuth 2.0 (код устройства или системный браузер сlocalhost-возвратом),GET /resourcesдля списков,revisionиsha256как ревизия; запись — проверкаrevisionперед получением ссылки загрузки, загрузка во временное имя иmoveсoverwrite=falseпосле повторной проверки (у REST нет атомарногоIf-Match— окно гонки сжимается до долей секунды, честно описано в справке). - Nextcloud — это WebDAV плюс вход Login Flow v2 (браузер → пароль приложения выдаёт сервер, пароль пользователя программа не видит).
Честный конфликт (макет 07)
- Открытие из облака: файл скачивается в локальный кэш
…/MOffice/cloud/<store>/<path>вместе с ревизией (ETag/revision); документ редактируется как локальный (вся защитаsaved_file.rsработает). - Сохранение: сначала локально (атомарная запись, как сейчас) → затем
put(expect = прочитанная ревизия). - Ответ «конфликт» (412 / несовпадение ревизии) → диалог: две
миниатюры («Ваша версия, 12:04» / «Версия Ивановой И., 12:01»), для
Write — сравнение абзацами (изменён обоими / только ими / только вами),
три действия и отмена:
- Оставить мою — их версия сначала копируется на
сервере рядом (
Договор (Иванова И., 12-01).docx), затем наша пишется сexpect= их ревизия (если за это время снова изменили — диалог повторяется); - Взять их — наша сохраняется рядом копией
(
… (моя версия, 12-04).docx), окно перезагружает их версию; - Сохранить обе — наша уходит отдельным новым файлом
(
If-None-Match: *), их не трогаем; - Отмена — ничего не отправляется, правки остаются в окне и в локальном кэше. Инвариант (проверяется тестами): ни одна версия не исчезает без явного действия пользователя; любая ветка оставляет обе версии хотя бы в одном месте (сервер или кэш).
- Оставить мою — их версия сначала копируется на
сервере рядом (
- Значки состояния в Hub: по сравнению ревизии в кэше и
statсервера при открытии раздела и раз в 60 с для открытых документов (без фоновой синхронизации всей папки).
Офлайн-очередь
- Очередь — журнал на диске (
cloud/queue.jsonl, одна строка = файл, локальная версия-хеш, ожидаемая ревизия, попытки), переживает перезапуск и падение. Повторное сохранение того же файла в очереди заменяет запись (отправляется последняя версия, ожидаемая ревизия — исходная). - Возврат сети определяется попыткой (экспоненциальная пауза 5 с → 5 мин) и событиями ОС о сети, если доступны.
- При отправке очереди конфликт → тот же диалог (как в макете: «При отправке очереди выяснилось…»).
- Без сети список папки — из кэша с плашкой «Нет сети · показано то, что было при последней синхронизации».
Учётные данные — связка ключей ОС
| ОС | Хранилище | Как (свой код, № 40) |
|---|---|---|
| macOS | Keychain | Security.framework:
SecItemAdd/CopyMatching/Update/Delete
(kSecClassInternetPassword), вызовы через FFI, как в
meridian-platform |
| Windows | Диспетчер учётных данных | CredWriteW/CredReadW/CredDeleteW
(advapi32), тип CRED_TYPE_GENERIC, имя
MOffice/cloud/<id> |
| Linux | Secret Service (GNOME Keyring, KWallet ≥ 5.97) | свой D-Bus-клиент dbus.rs:
org.freedesktop.secrets — OpenSession(plain),
CreateItem, SearchItems,
GetSecrets; при отсутствии службы — не
сохраняем пароль (спрашиваем при каждом запуске), а не пишем
его в файл |
Пароль и токены никогда не попадают в журналы, настройки, отчёты о
сбоях и queue.jsonl (в настройках — только идентификатор
записи связки ключей). Модуль meridian-keyring с трейтом
SecretStore { get, set, delete } — общий и для
лицензии/MOffice ID, и для ключей Assist (ADR Ф8-2).
Риски
| Риск | Что делаем |
|---|---|
| Яндекс меняет REST API или ограничивает сторонние приложения | WebDAV-адаптер работает и с Яндексом (с паролем приложения) — запасной путь, переключается в настройках подключения |
| Регистрация OAuth-приложения в Яндексе требует юр. данных и проверки | заявка владельца заранее (до 1.03.2027) |
Сервер без ETag/If-Match (старые
WebDAV) |
предупреждение при подключении; сравнение
getlastmodified+размер; в справке — честно о гонке |
Потеря правок при обрыве в середине PUT |
локальная версия сохранена до отправки; повтор из очереди;
PUT во временное имя + MOVE там, где сервер не
атомарен |
| Большие файлы (сотни МБ) и медленная сеть | потоковая выгрузка с прогрессом и отменой; чанки Nextcloud
(/uploads/) — только если понадобится по замеру |
| Нет Secret Service на Linux | ввод пароля при запуске, без сохранения; описано в справке |
Оценка и задачи
Итого 24–31 сд (бюджет плана 20–30; +1–2 сд на расширение транспорта, которого в бюджете не было).
| № | Задача | Сд | Владелец файлов | Готово, когда |
|---|---|---|---|---|
| C1 | meridian-net:
Transport::send(HttpRequest) -> HttpResponse (метод,
заголовки, тело потоком, статус, заголовки ответа) для curl,
NSURLSession, libcurl,
WinHTTP |
2–3 | S1 | WebDAV-методы через все реализации на тестовом сервере; GET-API обновлений не изменился |
| C2 | meridian-keyring: Keychain, Credential Manager, Secret
Service |
3–4 | новая (общая) | запись/чтение/удаление на 3 ОС; пароль не виден в ps,
журналах и файлах (тест поиска строки) |
| C3 | meridian-cloud: трейт CloudStore, кэш,
ревизии, очередь, инварианты конфликта |
4–5 | новая | модельные тесты: 200 сценариев (обрыв сети, два клиента, падение процесса) — 0 потерянных версий |
| C4 | WebDavStore (+ Nextcloud Login Flow v2) |
3–4 | новая | против Nextcloud 29 и Apache mod_dav в Docker на sagr:
все операции, 412 при чужой ревизии |
| C5 | YandexDiskStore (OAuth, REST, ревизии) |
3–4 | новая | против тестового аккаунта Яндекса: все операции, конфликт обнаруживается |
| C6 | Hub: раздел «Облако», подключение, обзор, значки, открыть/сохранить в облако | 4–5 | S2 | сценарии макета 07 на macOS и Linux |
| C7 | Диалог конфликта (миниатюры, сравнение абзацев Write, три действия), очередь в строке состояния | 3–4 | S2 + S3 | сценарий «Иванова сохранила раньше» проходит тремя ветками; «Нет сети» копит и отправляет |
| C8 | Стенд и квитанция: Nextcloud + WebDAV в Docker на sagr
(cloud-test.24oros.ru, отдельный поддомен), 200 сценариев с
обрывом сети, ворота |
2 | S5 | квитанция cloud-lite-*.json: 0 потерянных правок,
конфликт всегда даёт выбор |
Порядок: C1 и C2 параллельно → C3 → (C4 ‖ C5) → C6 → C7 → C8.
Решения владельца
- Подтвердить: Яндекс.Диск через REST API с OAuth (основной путь), WebDAV — запасной.
- Зарегистрировать OAuth-приложение «MOffice» в Яндекс ID (нужен аккаунт владельца/ИП; срок — до 1.03.2027).
- Разрешить тестовый Nextcloud на sagr (отдельный поддомен, только тестовые данные).
- Облако-lite — в Free или только в Pro? (рекомендую: подключение WebDAV/Nextcloud — Free, Яндекс.Диск — Free; платное отличие Pro — Assist; облако снимает возражение «нет общей папки»).
- Политика на Linux без Secret Service: спрашивать пароль при запуске (рекомендую) или хранить в файле, зашифрованном ключом устройства (слабее).