Загрузки и скачивания

Файлы любого размера попадают в Arkvory по частям, а остановившаяся передача может продолжиться с того места, где остановилась. Эта страница показывает, как это делается в консоли, через arkvoryctl, через SDK и через HTTP API.

Для загрузки нужны действия upload.create, upload.read, upload.write и upload.complete. На уровне групп это доступ на запись. Для скачивания нужно content.read. См. Права.

Загрузка файла

Каждая загрузка проходит одни и те же шаги. Клиент вычисляет SHA-256 всего файла и открывает сессию загрузки с именем файла, размером и контрольной суммой. Он отправляет файл по частям. Когда все части на месте, сервер собирает их, проверяет контрольную сумму и публикует файл как неизменяемый артефакт.

В консоли

Нажмите Загрузка на боковой панели или Загрузить файл в верхней панели.
Выберите файл в поле Файл для загрузки. Консоль один раз читает весь файл, чтобы вычислить его контрольную сумму (Проверка целостности файла…). Для файла в десятки гигабайт это занимает некоторое время, прежде чем будет отправлен первый байт.
Нажмите Загрузить / продолжить. Индикатор в блоке Состояние передачи показывает ход передачи.
Когда файл опубликован, показывается его ID. Откройте раздел Артефакты, чтобы увидеть его.

Кнопка Пауза останавливает передачу и сохраняет уже полученные части. Если во время загрузки вы попытаетесь покинуть страницу, браузер предупредит вас. Консоль не отправляет с файлом ни меток, ни метаданных. Добавьте их потом в разделе Свойства артефакта; см. Файлы по пути.

С arkvoryctl

bash

arkvoryctl upload ./Build/Game.zip --label test
arkvoryctl upload ./Build/Game.zip --file metadata.json --state ./job-state/game.json
arkvoryctl uploads status 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11
arkvoryctl uploads cancel 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11

upload выводит артефакт, когда он опубликован. --label добавляет одну метку. --file указывает JSON-файл с labels и metadata и имеет приоритет. Чтобы сохранить файл под путём, используйте put; чтобы опубликовать UPack, используйте packages publish. См. Командная строка.

С SDK

typescript

const session = await releases.uploads.create(idempotencyKey, {
  name: 'Game.zip',
  size: String(file.size),
  sha256,
  labels: ['test'],
  metadata: { commit: 'abc123' },
});
const artifact = await releases.uploads.resume(session.id, file, {
  onProgress: (bytes) => console.log(bytes),
});

resume отправляет части, которых нет на сервере, и завершает загрузку. Полный пример с вычислением хеша в Node.js приведён в разделе TypeScript SDK.

С HTTP API

bash

curl -X POST "$ARKVORY/api/v1/repositories/releases/uploads" \
  -H "Authorization: Bearer $ARKVORY_KEY" -H "Idempotency-Key: game-1234" \
  -H "Content-Type: application/json" \
  -d '{"name":"Game.zip","size":"73400320","sha256":"<64 hex-символа>"}'

curl "$ARKVORY/api/v1/repositories/releases/uploads/$ID/parts" -H "Authorization: Bearer $ARKVORY_KEY"

curl -X PUT "$ARKVORY/api/v1/repositories/releases/uploads/$ID/parts/0" \
  -H "Authorization: Bearer $ARKVORY_KEY" -H "Content-Type: application/octet-stream" \
  -H "X-Content-SHA256: <64 hex-символа этой части>" --data-binary @part-0.bin

curl -X POST "$ARKVORY/api/v1/repositories/releases/uploads/$ID/complete" \
  -H "Authorization: Bearer $ARKVORY_KEY"

Размер — десятичная строка. Idempotency-Key — от 1 до 128 букв, цифр, ., _, : или -. В ответе на первый вызов есть id загрузки и expiresAt. Второй вызов возвращает размер части partBytes и уже сохранённые части. Каждая часть имеет ровно этот размер, кроме последней. Операции: createUpload, listUploadParts, putUploadPart и completeUpload (Загрузки).

Для небольшого файла есть два более простых способа. PUT /uploads/{id}/content отправляет весь файл одним запросом. PUT /raw/<путь> создаёт сессию, отправляет байты и сохраняет их под путём одним запросом, как это делает curl -T. Оба запроса должны завершиться в течение 30 минут. Для всего большого или медленного используйте части. См. Обычные файлы. Пустой файл отправляется одним запросом.

Какого размера может быть файл

Ограничение	Значение
Размер части	8 МиБ для файлов примерно до 78 ГиБ. Файлы больше используют части 16, 32, 64 МиБ и так далее, до 1 ГиБ, чтобы файлу никогда не требовалось больше 10 000 частей.
Частей в одной загрузке	10 000 (индексы от 0 до 9999)
Наибольший файл	10 000 частей по 1 ГиБ, около 10 ТиБ
Более низкий предел	Администратор может задать его через `ARKVORY_MAX_OBJECT_BYTES`
Имя файла	От 1 до 240 символов, без `/`, `\` и управляющих символов

Сервер выбирает размер части при создании загрузки и сохраняет его на всё время загрузки. GET /api/v1/capabilities показывает maxObjectBytes, partBytes, maxPartBytes и maxParts. Консоль отказывается принимать файл больше лимита сервера ещё до начала загрузки.

Клиент держит в памяти одну часть, пока вычисляет её хеш и отправляет. Для файлов больше 78 ГиБ размер части, а значит и объём памяти, растёт до 1 ГиБ.

Свободного места на диске сервера должно хватать для частей и собранного файла на некоторое время. Если диск заполнен, сервер отклоняет загрузку с ошибкой 507 storage_full.

Продолжение загрузки

Сессия загрузки сохраняет свои части после сбоя. Чтобы продолжить, дайте клиенту тот же файл и ту же сессию.

Консоль. В пределах открытой вкладки нажмите Загрузить / продолжить ещё раз после Пауза. После закрытия вкладки сохраните ID загрузки. Разверните Продолжить загрузку: поле ID загрузки показывает ID, пока идёт загрузка. Позже выберите тот же файл, введите туда ID и нажмите Загрузить / продолжить. Консоль сверяет части с вашим файлом. Если файл другой, она останавливается и сообщает об этом. Кнопка Новая загрузка очищает оба поля и начинает новую загрузку.

Поле Ключ защиты от повторов — второй путь назад. Консоль заполняет его сама. Тот же ключ с тем же файлом возвращает ту же сессию, а не создаёт вторую.

arkvoryctl. Запустите ту же команду с теми же параметрами. Перед первым запросом клиент сохранил контрольную точку <файл>.arkvory-upload.json рядом с исходным файлом или файл, указанный в --state. Чтобы опубликовать те же байты как новый артефакт, используйте новый --state. В CI сохраняйте исходный файл и папку состояния между повторными запусками. Изменение файла, сервера, репозитория или параметров даёт checkpoint_mismatch (код выхода 6).

SDK. Снова вызовите resume с сохранённым ID сессии и тем же файлом. Если потерян даже ответ на create, вызовите create с тем же ключом идемпотентности и тем же дескриптором: он вернёт ту же сессию.

HTTP. Прочитайте сохранённые части через listUploadParts, затем отправьте недостающие индексы. Повторная отправка части с теми же байтами безопасна. Другие байты для уже сохранённого индекса отклоняются с ошибкой 409 upload_state.

Клиенты также сами повторяют запрос после сбоя сети или после 408, 429, 502, 503 и 504: до 20 раз на одну операцию, с паузой, которая растёт от 0,5 до 60 секунд и учитывает Retry-After. Для медленных каналов в arkvoryctl есть параметры --retries и --attempt-timeout.

Продолжить загрузку может только учётная запись или ключ, которые её создали. Для всех остальных она не существует. Ротация ключа сервиса сохраняет учётную запись, поэтому новый ключ продолжает загрузку.

Контрольные суммы

Перед загрузкой. Консоль, CLI и SDK вычисляют SHA-256 файла и отправляют его в сессии.
Каждая часть. Заголовок X-Content-SHA256 содержит контрольную сумму части. Часть, байты которой не совпадают, отклоняется с ошибкой 422 integrity_mismatch и не сохраняется.
В конце. Перед публикацией сервер сверяет размер и SHA-256 собранного файла с сессией. Несовпадение — это 422 integrity_mismatch; CLI завершается с кодом 5. Артефакт не появляется.
Скачивание. Консоль, CLI и SDK проверяют SHA-256 всего файла, прежде чем передать его. Итоговый файл появляется только после успешной проверки.

ETag файла — его контрольная сумма: "sha256:<64 hex-символа>". В свойствах артефакта показан SHA-256, а кнопка Копировать копирует его.

Задание завершения

Сборка большого файла занимает время. Файлы меньше 16 ГиБ completeUpload собирает прямо в запросе, и это может занять до 30 минут. Начиная с 16 ГиБ SDK, а значит, консоль и CLI, просят обработчик завершить загрузку: enqueueCompletion отвечает 202 и возвращает задание, а клиент опрашивает getCompletionJob, пока состояние не станет completed или failed. У неудавшегося задания есть код ошибки, например integrity_mismatch.

Для заданий должен работать обработчик (worker). Он пробует выполнить задание до 5 раз с растущей паузой и сразу сдаётся на ошибках, которые повтор не исправит. Повторный enqueueCompletion возвращает то же задание. Если сервер перезапускается, задание продолжается. Загружать файл заново не нужно.

Срок действия загрузки

Незавершённая сессия загрузки истекает через 7 дней после создания. Время указано в expiresAt, не продлевается и не сдвигается, когда вы отправляете части. После этого части и complete отклоняются с ошибкой 409 upload_expired. Начните новую загрузку. Опубликованные файлы не истекают.

Сервер удаляет истёкшие сессии и их части в фоновом режиме. Чтобы отказаться от загрузки раньше, используйте arkvoryctl uploads cancel ID или cancelUpload. Отмена — это не пауза: части удаляются.

Скачивание файла

В консоли

Нажмите Скачать рядом с файлом в разделе Артефакты или в свойствах артефакта. Браузер спросит, куда сохранить файл. Файл попадает в очередь в разделе Скачивания. Очередь записывает данные во временную копию, проверяет SHA-256 и только потом заменяет целевой файл.

Для очереди нужен Chrome или Edge на HTTPS или на локальном компьютере, потому что большой файл записывается через доступ браузера к файловой системе. В других браузерах используйте CLI или SDK.

Состояния скачивания: В очереди, Скачивание, Повтор, Приостановлено, Сохранение проверенного файла…, Проверено и сохранено, Ошибка и Отменено. Кнопки:

Кнопка	Действие
Продолжить / повторить	Продолжить приостановленное или неудавшееся скачивание с сохранённой части
Отменить	Отменить одно скачивание и удалить его временную копию
Приостановить все / Продолжить очередь	Приостановить и возобновить всю очередь
Отменить ожидающие	Отменить ожидающие скачивания
Отменить все	Отменить все скачивания
Убрать завершённые	Убрать завершённые строки, чтобы освободить место (в очереди помещается 64)
Восстановить очередь	После перезагрузки страницы вернуть незавершённые скачивания

В блоке Настройки очереди есть Одновременные скачивания (от 1 до 8, по умолчанию 2), Интервал запуска, мс (от 0 до 60 000 мс, по умолчанию 250) и Предел ожидания, секунды (от 1 до 1800 секунд, по умолчанию 300). Нажмите Применить ограничения, чтобы применить их. Они не повышают лимиты сервера.

После перезагрузки или закрытия вкладки снова войдите на тот же сервер под той же учётной записью, откройте Скачивания и нажмите Восстановить очередь. Восстановленные скачивания ждут на паузе. Нажмите Продолжить / повторить у каждого и снова выберите целевой файл. Браузеру нужно свободное место для временной копии.

С arkvoryctl

bash

arkvoryctl download 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 ./Game.zip
arkvoryctl get builds/game/1.4/Game.zip ./Game.zip
arkvoryctl packages download app ./app.upack --range ^1.4 --stage release

Пока идёт скачивание, рядом с целевым файлом лежат <выходной файл>.arkvory-part и <выходной файл>.arkvory-download.json. После прерывания запустите ту же команду снова. Итоговый файл появляется только после проверки SHA-256. Существующий целевой файл никогда не перезаписывается (destination_exists, код выхода 6).

С HTTP: диапазоны и ETag

downloadArtifact возвращает байты артефакта. HEAD возвращает только заголовки.

bash

curl -fL -H "Authorization: Bearer $ARKVORY_KEY" -C - -o Game.zip \
  "$ARKVORY/api/v1/repositories/releases/artifacts/$ID/content"

Accept-Ranges: bytes. Отправьте Range: bytes=1048576-, bytes=0-1023 или bytes=-500 для одного диапазона. Ответ — 206 с Content-Range. Несколько диапазонов сразу не поддерживаются: сервер отправляет весь файл. Начало за пределами файла даёт 416.
ETag — это "sha256:<hex>". If-None-Match с ним даёт 304. If-Range с ним продолжает диапазон, только если файл не изменился; иначе приходит весь файл.
curl -C - возобновляет скачивание. Адреса по имени разрешаются заново при каждом запросе, например packages/content?name=app&range=^1.4, поэтому файл может измениться между двумя вызовами. Чтобы безопасно возобновлять такие скачивания, отправляйте полученный ETag в If-Range или сначала найдите артефакт по имени и скачивайте по ID артефакта.

SDK читает содержимое диапазонами по 8 МиБ и проверяет каждый из них. См. TypeScript SDK.

Ссылки для людей без ключа

Ссылка на скачивание позволяет получить один файл без какого-либо ключа: тестировщику, заказчику, сборочной машине, у которой нет учётных данных. Ссылка открывает только этот артефакт, для GET и HEAD, пока не истечёт. Она работает с curl -C - и с диапазонами.

В консоли откройте артефакт в разделе Свойства артефакта и нажмите Ссылка на скачивание. Консоль копирует ссылку и показывает её вместе со сроком действия. Ссылка действует один час. Кнопка появляется, только если вы можете скачать файл.

bash

arkvoryctl link 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 --ttl 900

bash

curl -X POST "$ARKVORY/api/v1/repositories/releases/artifacts/$ID/links" \
  -H "Authorization: Bearer $ARKVORY_KEY" -H "Content-Type: application/json" \
  -d '{"ttlSeconds":900}'

Срок действия — от 60 секунд до 24 часов (86 400 секунд), по умолчанию один час. В ответе есть token, начинающийся с dtl_, url и expiresAt. CLI и SDK выводят полный URL. API возвращает путь, который нужно добавить к адресу сервера.

Ссылка — это секрет. Любой, у кого она есть, может скачать файл. Отозвать ссылку до истечения срока нельзя, поэтому делайте её короткой. Относитесь к URL как к ключу: не публикуйте его в чатах и открытых журналах. Журналы прокси-сервера и история браузера могут его записать. См. Ссылки на скачивание.

Лимиты и очереди

Администратор задаёт, сколько передач сервер выполняет одновременно и с какой скоростью. По умолчанию сервер выполняет одновременно 2 загрузки и 16 скачиваний, а одна учётная запись — 1 загрузку и 4 скачивания. Остальные ждут в очереди до 20 секунд. Если очередь заполнена или ожидание закончилось, сервер отвечает 503 с Retry-After, а клиенты ждут и повторяют запрос. Лимит в байтах в секунду, если он задан, замедляет передачи, но не останавливает их. Пользователи не видят и не меняют эти лимиты. Значения указаны в разделе Переменные окружения.

Ошибки

Ответ	Причина	Что делать
`409 upload_expired`	Сессии больше 7 дней	Начните новую загрузку
`409 upload_state`	Загрузка уже опубликована или отменена, либо у сохранённой части другие байты	Начните новую загрузку или проверьте, что используете тот же файл
`409 parts_incomplete`	Некоторые части не поступили	Продолжите загрузку
`409 part_mismatch`	Части не соответствуют запланированному размеру части или индексам	Возьмите размер части из `listUploadParts` и продолжите загрузку
`409 idempotency_mismatch`	Ключ использован для другого файла	Используйте новый ключ
`422 integrity_mismatch`	Контрольная сумма не совпадает	Отправьте исходный файл ещё раз
`507 storage_quota`	Квота репозитория исчерпана	Удалите старые сборки или запросите бо́льшую квоту
`507 storage_full`	Диск сервера заполнен	Обратитесь к администратору
`503` с `Retry-After`	Сервер занят	Подождите, клиенты повторяют запрос сами

Полный список — в разделе Ошибки.

Командная строка (arkvoryctl) и TypeScript SDK
Файлы по пути и Пакеты
Справочник API: Загрузки, Ссылки на скачивание, Артефакты

Загрузки и скачивания ​

Загрузка файла ​

В консоли ​

С arkvoryctl ​

С SDK ​

С HTTP API ​

Какого размера может быть файл ​

Продолжение загрузки ​

Контрольные суммы ​

Задание завершения ​

Срок действия загрузки ​

Скачивание файла ​

В консоли ​

С arkvoryctl ​

С HTTP: диапазоны и ETag ​

Ссылки для людей без ключа ​

Лимиты и очереди ​

Ошибки ​

Связанные страницы ​

Загрузки и скачивания

Загрузка файла

В консоли

С arkvoryctl

С SDK

С HTTP API

Какого размера может быть файл

Продолжение загрузки

Контрольные суммы

Задание завершения

Срок действия загрузки

Скачивание файла

В консоли

С arkvoryctl

С HTTP: диапазоны и ETag

Ссылки для людей без ключа

Лимиты и очереди

Ошибки

Связанные страницы