Интерфейс между API и Saver

API передаёт принятый build request компоненту Saver через RabbitMQ. Формат сообщения: JSON, content-type application/json, delivery mode persistent.

RabbitMQ

API объявляет durable queue из конфигурации amqp_queue_name, привязывает её к amqp_exchange с пустым routing key и публикует сообщение в этот же exchange с пустым routing key.

Если включён DLX, очередь создаётся с аргументами:

x-dead-letter-exchange = <amqp_dlx>
x-overflow = reject-publish-dlx

Saver потребляет эту очередь с manual ack/nack. При успешной записи данных в TrackDB, Secret Manager и публикации события для Distributor сообщение ack'ается. При ошибке сообщение nack'ается без requeue и уходит в DLX.

Payload API -> Saver

API принимает внешний BuildRequest, валидирует его и преобразует в SaverRequest. image_path разбивается на registry_name и image_name; user, user_gid и ulid добавляются API автоматически.

{
  "image_tag": ["latest", "1.0.0"],
  "image_arch": ["amd64", "arm64"],
  "config_path": "/path/to/config.yaml",
  "registry_name": "registry.example.org",
  "image_name": "project/image",
  "registry_creds": "registry-login:registry-password",
  "git_url": "https://github.com/user/repo.git",
  "git_creds": "git-login:git-password",
  "build_git_branch": "master",
  "git_dockerfile_url": "https://github.com/user/dockerfiles.git",
  "git_dockerfile_branch": "master",
  "build_context_path": ".",
  "build_dockerfile_path": "images/app/Dockerfile",
  "test_entrypoints": {
    "amd64": [["rpm", "--eval", "%_host_cpu"]],
    "all": [["nginx", "-v"]]
  },
  "annotations": {
    "org.opencontainers.image.source": "https://github.com/user/repo",
    "org.opencontainers.image.version": "1.0.0"
  },
  "user_gid": 200,
  "user": "alexander",
  "ulid": "01JBV2S4PGNV87EGC5WKYA0RND"
}

Поля:

Поле	Тип	Описание
`image_tag`	array[string]	Теги образа. Full API добавляет `latest`, если пользователь не указал тег; `altflow-api-lite` может передать пустой массив.
`image_arch`	array[string]	Нормализованные архитектуры: `amd64`, `arm64`, `i586`, `loongarch64`, `riscv64`.
`config_path`	string	Опциональный путь к конфигурации сборки.
`registry_name`	string	Registry из `image_path`.
`image_name`	string	Имя образа из `image_path`.
`registry_creds`	string	Учётные данные registry в формате `login:password`.
`git_url`	string	HTTPS URL Git-репозитория.
`git_creds`	string	Опциональные учётные данные Git в формате `login:password`.
`build_git_branch`	string	Опциональная ветка репозитория `git_url`.
`git_dockerfile_url`	string	Опциональный HTTPS URL отдельного Git-репозитория с Dockerfile. Пустая строка означает, что Dockerfile находится в `git_url`.
`git_dockerfile_branch`	string	Опциональная ветка `git_dockerfile_url`. Допустима только если `git_dockerfile_url` не пустой; это проверяет API до отправки в Saver.
`build_context_path`	string	Контекст сборки внутри `git_url`. API заполняет default: каталог Dockerfile для общего репозитория или `.` при вынесенном Dockerfile.
`build_dockerfile_path`	string	Путь к Dockerfile: относительно `git_url`, если `git_dockerfile_url` пустой — иначе относительно `git_dockerfile_url`.
`test_entrypoints`	object<string,array[array[string]]>	Команды для стадии `TEST`, сгруппированные по архитектурам. Ключ `all` задаёт общий набор команд для архитектур без собственного набора; пустой объект означает пропуск стадии.
`annotations`	object<string,string>	OCI annotations, прошедшие валидацию API. Saver сохраняет их в TrackDB и передаёт в первичное событие `BUILD/NEW`.
`user_gid`	number	GID для TrackDB events: в full API используется `200`, в lite API `100`.
`user`	string	Пользователь, определённый API. В lite режиме используется системное значение `registry.altlinux.org`.
`ulid`	string	ULID задачи; в TrackDB пишется как `taskId`.

Дальнейшие действия Saver

После получения сообщения Saver:

Разбирает git_creds и registry_creds на пары username/password.
Сохраняет credentials задачи в Secret Manager по task id.
Пишет исходное событие BUILD/NEW в TrackDB таблицу imageEvents; поля с default-значениями ClickHouse не передаются в insert.
Публикует stage-event для Distributor в очередь distributor_queue.

Stage-event для Distributor описан в интерфейсе Stager/Distributor; Saver использует тот же формат для первичного события BUILD/NEW.

API уже нормализует зависимость репозиториев перед Saver: git_url всегда обязателен и хранит context, git_dockerfile_url опционален и хранит только Dockerfile. build_context_path никогда не относится к git_dockerfile_url.

Altflow Docs

Интерфейс между API и Saver

RabbitMQ

Payload API -> Saver

Дальнейшие действия Saver