Деревья папок
Агенту развёртывания или заданию CI часто нужна целая папка: сборка игры, набор инструментов, дерево конфигурации. arkvoryctl tree публикует папку одним ZIP-артефактом, получает её в папку, сверяет папку с ним и восстанавливает только отличающиеся файлы. Артефакт — обычный ZIP-файл: его читают консоль, API и любая программа для ZIP, а резервные копии хранят его как любой другой артефакт.
Эти команды входят в бесплатное ядро. Им нужны те же права, что и для загрузок и скачиваний: см. Загрузки и скачивания.
Публикация папки
arkvoryctl tree push ./Build/Game --name game-1.4.zip --label release| Параметр | Значение |
|---|---|
--name NAME.zip | Имя артефакта. По умолчанию — имя папки с .zip. Имя должно заканчиваться на .zip. |
--label TAG | Метка артефакта |
--file METADATA.json | Метки и метаданные, как для upload |
--compress | Сжимать записи (deflate). Без этого параметра файлы хранятся как есть. |
Результат показывает id артефакта, его size, sha256 и число файлов в entries.
- Одна и та же папка даёт один и тот же архив. Файлы идут в порядке путей, у каждой записи дата 1980-01-01, и из свойств файловой системы сохраняется только одно: файл, который владелец может выполнять, получает режим 755, любой другой — 644. Повторная публикация неизменённой папки даёт те же байты и тот же SHA-256.
- Прерывания. Архив собирается рядом с папкой (
.<папка>.arkvory-tree.zip) и загружается по частям с контрольной точкой. После Ctrl+C или сбоя сети снова запустите ту же команду: она соберёт тот же архив и продолжит загрузку. После успеха оба файла удаляются. - Что отклоняется. Символические ссылки, точки соединения (junction), устройства и каналы внутри папки (
tree_entry_unsupported), имена, недопустимые в Windows (unsafe_name), и два имени, отличающиеся только регистром букв (case_collision). Пустые папки не сохраняются. - Без сжатия или со сжатием. Без
--compressбайты каждого файла занимают непрерывный диапазон архива. Тогда сервер может отдать один файл по диапазону байтов, а восстановление передаёт ровно байты отличающихся файлов. С--compressархив меньше, а восстанавливаемый файл распаковывается на вашей машине.
Получение папки
arkvoryctl tree pull 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 ./Game- Пустая или отсутствующая папка получает архив целиком. Он скачивается рядом с папкой с контрольными точками, поэтому прерванное получение продолжается с того места, где остановилось. После проверки SHA-256 файлы распаковываются в новую папку рядом с целевой, и та занимает место целевой.
- Папка с файлами приводится к дереву. Если у сервера есть оглавление, скачиваются только отличающиеся файлы, каждый по своему диапазону байтов, а файлы, которых нет в дереве, удаляются. Без оглавления скачивается весь архив, и распакованная папка заменяет старую.
Родительская папка должна существовать. Файл внутри целевой папки заменяется за один шаг: он записывается во временный файл рядом, проверяется и переименовывается. Программа, читающая файл, видит либо старую, либо новую версию.
Проверка папки
arkvoryctl tree verify 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 ./GameРезультат перечисляет отсутствующие файлы (missing), несовпадающие файлы (mismatched: другой размер или другой SHA-256) и лишние файлы, которых нет в дереве (extra), а их количество — в counts. Каждый список показывает не больше 1000 путей. ok равно true, если ничего не отсутствует и не расходится; лишние файлы на него не влияют. Код выхода — 0, если ok равно true, и 5 в остальных случаях.
Восстановление папки
arkvoryctl tree repair 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 ./GameВосстановление заново записывает все отсутствующие и несовпадающие файлы и оставляет лишние. С оглавлением оно скачивает только записи этих файлов; fetchedBytes в результате показывает, сколько байтов архива прочитано. Без оглавления сначала скачивается весь архив.
Оглавление
После публикации архива обработчик (worker) сервера один раз читает его и записывает каждый файл: путь, размер, SHA-256 и место его байтов в архиве. Это делается для артефактов, имя которых заканчивается на .zip или .upack. Пока оглавление не готово или если архив нельзя проиндексировать, команды работают со всем архивом.
Сервер, у которого есть оглавление, предлагает zip-tree в tree ответа GET /api/v1/capabilities (см. arkvoryctl doctor); со старым сервером команды работают со всем архивом. Само оглавление возвращает операция getArtifactTree: status равно ready, pending или unavailable с причиной в reason.
reason | Значение |
|---|---|
not_archive | Имя артефакта не заканчивается на .zip или .upack |
invalid_archive | Файл не является читаемым ZIP-архивом |
unsafe_entry | Путь выходит за пределы архива, или запись является ссылкой или специальным файлом |
encrypted_entry | Запись зашифрована |
duplicate_entry | У двух записей один и тот же путь, в том числе без учёта регистра букв |
unsupported_method | Запись использует метод сжатия, отличный от stored и deflate |
crc_mismatch | Байты записи не совпадают с её контрольной суммой в архиве |
too_many_entries | Больше 100 000 записей |
too_large | Больше 100 ГиБ в распакованном виде |
Как проверяются файлы
- Каждый файл проверяется, прежде чем занять своё место. С оглавлением его размер и SHA-256 должны совпасть со значениями, которые сервер вычислил по опубликованному архиву. Без оглавления сначала проверяется SHA-256 всего архива, затем размер и CRC-32 каждого файла. При несовпадении команда останавливается с
checksum_mismatch(код выхода 5), а файл в папке остаётся как был. - Ничего не пишется за пределами папки. Пути из архива и от сервера считаются недоверенными данными. Путь, выходящий за пределы папки, отклоняется с
path_outside_root. Ссылка внутри папки, встреченная на пути к файлу, никогда не используется для перехода. Имена, недопустимые в Windows (CON,aux.txt,a:b, точка или пробел в конце), отклоняются сunsafe_nameв любой системе, поэтому дерево одинаково на Windows и Linux. - Режимы. Файл, распакованный из архива, получает режим 755, если архив помечает его исполняемым, иначе 644 (Linux и macOS). Файл, восстановленный по диапазону, сохраняет режим файла, который он заменяет.
Ускоренные передачи
Загрузка всего архива в tree push и его скачивание в tree pull идут через ту же передачу, что и upload и download. Клиентский модуль с расширением передачи может выполнять их, если сервер предлагает то же расширение; архив остаётся обычным ZIP, а его SHA-256 и каждый файл проверяются, как описано выше. Без модуля или если сервер его не предлагает, arkvoryctl использует собственную передачу.