Пакеты UPack

Пакет UPack — это ZIP-архив с именем и версией SemVer. Arkvory регистрирует каждую версию один раз и никогда не меняет её. Задание развёртывания запрашивает «app, версия ^1.4, стадия release» и получает ровно один файл.

Что такое пакет

UPack — это ZIP-файл с файлом upack.json в корне. Манифест называет пакет:

json

{
  "group": "acme/game",
  "name": "game-client",
  "version": "1.4.2"
}

Поле	Правило
`name`	Обязательное. От 1 до 128 букв, цифр, `.`, `_` или `-`
`version`	Обязательное. SemVer: `1.4.2`, `1.5.0-rc.1`, `2.0.0+build.7`. Не больше 128 символов
`group`	Необязательное. Сегменты из букв, цифр, `.`, `_` или `-`, разделённые `/`. Не больше 128 символов. По умолчанию пусто

Остальные поля остаются такими, как вы их записали, и возвращаются в списке пакетов. Манифест — не больше 64 КиБ. В архиве не должно быть абсолютных путей, .., символических ссылок, зашифрованных записей и повторяющихся имён; записей — не больше 100 000. Arkvory хранит архив байт в байт и не распаковывает его.

Идентичность пакета — это его группа, имя и версия; регистр букв при сравнении не учитывается. В пределах одного репозитория идентичность навсегда принадлежит одному архиву. Попытка зарегистрировать другой архив под существующей идентичностью отклоняется с ошибкой 409 version_exists. Повторная регистрация того же архива безопасна и ничего не меняет. Исправление публикуйте как новую версию.

Публикация пакета

Публикация — это загрузка и следующая за ней регистрация. Регистрация читает upack.json и записывает идентичность. Помимо действий загрузки вам нужны действия package.publish и artifact.read. См. Права.

В консоли

Загрузите архив в разделе Загрузка. См. Загрузки и скачивания.
Откройте артефакт в разделе Артефакты кнопкой Открыть.
В разделе Свойства артефакта нажмите Зарегистрировать UPack. Консоль покажет имя и версию, которые она зарегистрировала.

Теперь пакет появится в разделе Пакеты.

С arkvoryctl

bash

arkvoryctl packages publish ./build.upack --label test --state ./job-state/build.json --json
arkvoryctl packages register 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11

packages publish загружает архив с возможностью продолжения и регистрирует его. Если регистрация не удалась после загрузки, в ошибке указаны artifactId и стадия register. Запустите ту же команду снова: загрузка не повторяется, а двойная регистрация безопасна. packages register ID регистрирует уже загруженный артефакт. См. Командная строка.

С HTTP API и SDK

Загрузите архив, как описано в разделе Загрузки и скачивания, затем зарегистрируйте его:

bash

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

typescript

const entry = await releases.packages.register(uploaded.id);
console.log(entry.group, entry.name, entry.version);

Операция — registerPackage. Повреждённый архив, отсутствие upack.json или неверная версия дают 400 invalid_input.

Просмотр и фильтрация

В консоли откройте раздел Пакеты. Введите значение в поле Группа UPack или Имя пакета: оба поля сравниваются точно, без учёта регистра. Выберите столбец в поле Сортировать, порядок в поле Порядок (По возрастанию или По убыванию) и группировку в поле Группировать (Группа UPack, Имя пакета или Без группировки), затем нажмите Применить. Кнопка Сбросить сбрасывает форму. В таблице показаны группа, имя, версия и стадии каждой версии. Кнопка Открыть показывает артефакт. Кнопки Назад и Далее переключают страницы.

bash

arkvoryctl packages list --group acme/game --name game-client
arkvoryctl packages list --after <значение next из предыдущего ответа>

В API listPackages принимает group, name, sort (group, name или version), direction (asc или desc), groupBy (none, group или package), after и limit (от 1 до 100, по умолчанию 50). В ответе есть items (группа, имя, версия, artifactId и весь манифест), groups и next. Курсор принадлежит фильтрам, с которыми он получен. Используйте его только с теми же фильтрами.

typescript

const page = await releases.packages.list({
  name: 'game-client',
  sort: 'version',
  direction: 'desc',
});

Для просмотра списка нужно package.read. Чтобы искать по меткам или метаданным, см. Файлы по пути.

Версии и диапазоны

Arkvory сравнивает версии по старшинству SemVer. 1.10.0 новее 1.9.0. Версия с предрелизной частью, например 1.5.0-rc.1, считается более ранней, чем 1.5.0.

Выборка принимает name пакета и, по желанию, такие фильтры:

Фильтр	Значение
`group`	Группа. По умолчанию пусто: пакет, у которого есть группа, находится, только если вы её указали
точная версия	Одна версия. Регистр не учитывается
диапазон	Диапазон SemVer
`stage`	Только версии, у которых есть эта стадия (см. Стадии и продвижение)
предрелиз	Включать предрелизы. По умолчанию выключено
порядок	`version` (по умолчанию) или `promoted`

Диапазоны можно записывать так: 1.2.3, ^1.2, ~1.2.3, 1.x, >=1.0.0 <2.0.0, 1.0.0 - 1.4.0 и ^1 || ^3. Диапазон — не больше 256 символов. Точную версию и диапазон нельзя сочетать.

Без точной версии или диапазона выборка возвращает наибольшую стабильную версию — последнюю. Предрелизы выбираются, только когда включён фильтр предрелизов или когда сама точная версия либо диапазон называет предрелиз с тем же major.minor.patch. order promoted выбирает версию, которую последней отметили стадией, а не наибольшую, и требует указать стадию. Если ничего не подходит, сервер отвечает 404 not_found.

Скачивание пакета

Сначала найдите версию командой resolve, если хотите увидеть, что получите, или скачивайте сразу.

bash

arkvoryctl packages resolve game-client --group acme/game --range ^1.4 --stage release
arkvoryctl packages download game-client ./game-client.upack --group acme/game --range ^1.4 --stage release
arkvoryctl packages download game-client ./game-client.upack --exact 1.4.2 --group acme/game
arkvoryctl packages download game-client ./game-client.upack --group acme/game

Параметры: --group, --exact, --range, --stage, --prerelease и --order promoted. Для точной версии используйте --exact, потому что --version выводит версию клиента. resolve выводит группу, имя, версию, artifactId, sha256, size, publishedAt, stagedAt и стадии. download сначала находит версию, затем скачивает этот артефакт с возможностью продолжения и проверкой SHA-256, как в разделе Загрузки и скачивания. Клиенту нужны package.read, artifact.read и content.read.

В HTTP есть две операции. resolvePackage требует package.read и возвращает те же сведения, что и resolve. downloadPackageContent отправляет байты выбранной версии и требует только content.read. Она добавляет заголовки X-Arkvory-Artifact-Id и X-Arkvory-Package-Version.

bash

curl -fL -G -H "Authorization: Bearer $ARKVORY_KEY" -o game-client.upack \
  --data-urlencode "name=game-client" --data-urlencode "group=acme/game" \
  --data-urlencode "range=^1.4" --data-urlencode "stage=release" \
  "$ARKVORY/api/v1/repositories/prod/packages/content"

Адрес по имени разрешается при каждом запросе. Если вы возобновляете скачивание с диапазоном, файл мог измениться между двумя вызовами. Вместо этого скачивайте artifactId, полученный от resolve, или отправляйте ETag в If-Range.

typescript

const found = await prod.packages.resolve({
  name: 'game-client',
  group: 'acme/game',
  range: '^1.4',
  stage: 'release',
});
const stream = await prod.artifacts.downloadVerified(found.artifactId);

Агенту развёртывания, который должен только забирать сборки, выдайте ключ сервиса с одним content.read для HTTP-адреса или набор для чтения для arkvoryctl. См. Сервисные учётные записи и ключи для CI.

Метки, метаданные и вложения

Версия пакета — обычный артефакт, поэтому к ней применимо всё, что описано в разделе Файлы по пути: метки вроде test, staging и release, текстовые метаданные вроде git.commit, коллекции и вложения, например SBOM или подпись. Первые метки задайте при загрузке параметром --label test. Метки ничего не меняют в архиве. Это свободный текст, а не управляемый статус. Для одобрения, на которое может опираться развёртывание, используйте стадию. См. Стадии и продвижение.

Хранение старых версий

Правила хранения репозитория считают зарегистрированные пакеты. По умолчанию, если правила включены, сохраняются последние 10 сборок каждого пакета и канала. Канал — это метка test, staging или release. Версию со стадией, защищённой меткой, путём к файлу или привязкой в качестве вложения правила хранения никогда не удаляют. Правила хранения выключены, пока администратор не включит их и не согласится на удаление. См. Хранение.

Ошибки

Ответ	Значение
`400 invalid_input` при регистрации	Это не корректный ZIP-архив UPack, в корне нет `upack.json`, или неверны имя либо версия
`409 version_exists`	Эта идентичность уже принадлежит другому архиву. Опубликуйте новую версию. Так же завершается продвижение в репозиторий, в котором такая версия уже есть, но с другими байтами
`404 not_found` при поиске версии	Ничто не подходит под фильтры. Проверьте группу, диапазон и стадию
`403 permission_missing`	У ключа нет `package.read`, `package.publish` или `content.read`

Загрузки и скачивания
Стадии и продвижение
Командная строка (arkvoryctl)
Справочник API: Пакеты, Стадии и продвижение

Пакеты UPack ​

Что такое пакет ​

Публикация пакета ​

В консоли ​

С arkvoryctl ​

С HTTP API и SDK ​

Просмотр и фильтрация ​

Версии и диапазоны ​

Скачивание пакета ​

Метки, метаданные и вложения ​

Хранение старых версий ​

Ошибки ​

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

Пакеты UPack

Что такое пакет

Публикация пакета

В консоли

С arkvoryctl

С HTTP API и SDK

Просмотр и фильтрация

Версии и диапазоны

Скачивание пакета

Метки, метаданные и вложения

Хранение старых версий

Ошибки

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