ADR 0034: отдельный удалённый клиент arkvoryctl

Статус: принят. Дата: 2026-09-25. Owner: Ian Panaev.

Причина

Локальный привилегированный arkvory управляет жизненным циклом сервера. Клиентам и CI/CD нужен самостоятельный интерфейс к удалённому API, который не требует установки БД или доступа к каталогам сервера.

Решение

apps/cli — Node.js composition root с зависимостями только от публичных SDK/contracts. Имя команды arkvoryctl исключает пересечение с локальным arkvory. HTTP, ACL, retries, Range и проверка SHA-256 остаются в SDK. CLI отвечает за аргументы, профили, безопасный вывод, чтение локальных файлов, чекпойнты и публикацию скачанного файла.

Профили содержат URL, репозиторий и необязательный путь к файлу ключа. Сам ключ поступает из окружения или этого файла, не из аргументов. Изменение URL через ARKVORY_BASE_URL отключает неявное использование ключа профиля. SDK запрещает HTTP вне loopback, URL credentials и redirects. Общий AbortSignal и deadline SDK распространяются также на management response bodies.

Upload сохраняет descriptor и idempotency key до первого POST; затем ID сессии. Повтор команды сверяет исходный файл и endpoint. Файл читается через immutable file-backed Blob; контрольная сумма вычисляется потоково. Чекпойнт сохраняется и после завершения как квитанция идемпотентности.

Download хранит staging рядом с результатом, повторно хеширует весь префикс и запрашивает недостающий диапазон через SDK. После checksum mismatch staging сбрасывается. Публикация через hard link происходит только после завершения проверенного потока и fsync. Существующий конечный файл никогда не заменяется. Файловая система должна поддерживать hard links; сетевые файловые системы и FAT/exFAT не входят в гарантированный профиль. На POSIX дополнительно синхронизируется родительский каталог; Windows Node не предоставляет directory fsync.

Эксклюзивные lock-файлы исключают конкурентную запись. После штатной отмены блокировка снимается. После SIGKILL/отключения питания блокировка остаётся: оператор проверяет отсутствие владельца и вручную удаляет только lock. Автоматическое «воровство» lock по PID небезопасно при повторном использовании PID и общих дисках.

Нативный клиент поставляется отдельно: Windows per-user EXE на Inno Setup, Linux DEB/RPM; pinned Node включён. .cmd — только стандартный Windows command shim, установку выполняет EXE. Дополнительно один arkvoryctl.mjs для CI с Node 24. Клиентский bundle собирается один раз в portable candidate; native packaging копирует проверенные байты. Релиз публикует проверенный inventory, без повторной сборки. Обновление клиента — повторная установка выбранного стабильного релиза, без скрытого фонового updater.

Проверки и ограничения

Unit gate: потеря create response, идемпотентность, конфликт исходного файла, целостность, атомарная публикация, блокировка, ограничение локальных JSON, SDK cancellation/deadline. Integration gate: реальный API/PostgreSQL, продолжение upload/download через новый CLI-процесс, metadata CAS, ACL и отсутствие секретов в stdout/stderr. Deployment gate проверяет независимый bundle; native gate устанавливает/переустанавливает/удаляет клиент и сохраняет профили, отдельно проверяет RPM на Fedora.

CLI не является полным зеркалом административной консоли: не выдаёт новые ключи, не меняет пользователей, политики хранения или topology. Возможности доступны в SDK/API; расширять CLI следует отдельными командами с явными правами и предохранителями. Подпись Windows и публикация релиза требуют отдельного релизного процесса. Native target пока Windows/Linux x64, ARM64 не заявлен.