validator/infra/forcad-local

forcad-local

Автоматизированный локальный оркестратор для запуска ForcAD + игровых сервисов + чекеров в контейнерах.

Инструмент делает:

• auto-discovery сервисов в переданной папке;
• preflight-проверки структуры сервисов и чекеров;
• containerized сборку checker-артефактов (например make для archive) без хостовых dev-пакетов;
• auto-cleanup хвостов прошлых запусков перед новым up;
• prewarm k3d/k3s образов перед деплоем k3d-сервисов;
• retry для k3d-деплоя и rollback при ошибке (настраивается);
• генерацию runtime-конфига ForcAD без правок исходников борды/сервисов;
• запуск light smoke-check check для каждого сервиса без полного ForcAD стека;
• опциональный full режим с полным ForcAD стеком;
• команды up, down, status, validate.

Требования

• docker + docker compose
• Python 3.10+
• Для Helm/k3d-профилей сервисов: helm, kubectl, k3d (если требуется конкретному сервису)

Базовый запуск

python3 infra/forcad-local/forcad_local.py validate \
  --services-root /path/to/services \
  --checkers-root /path/to/checkers

python3 infra/forcad-local/forcad_local.py up \
  --services-root /path/to/services \
  --checkers-root /path/to/checkers \
  --mode light

python3 infra/forcad-local/forcad_local.py status

python3 infra/forcad-local/forcad_local.py down

После up борда доступна по http://127.0.0.1:8080/ (или через --board-port). Это относится только к --mode full. В --mode light борда не запускается.

Какие структуры поддерживаются

Для сервиса в services-root/<service_name>/:

1. Compose-профиль
   • должен быть docker-compose.yml
2. Script/Helm-профиль
   • deploy.sh, либо
   • redeploy.sh, либо
   • deploy/chart/values.yaml (с возможным build-docker.sh)

Для чекера в checkers-root/<service_name>/:

• должен быть checker.py или *.checker.py
• если есть requirements.txt (или requirments.txt) — зависимости автоматически объединяются
• если есть Makefile — сборка выполняется внутри builder-контейнера (cpp-make профиль по умолчанию)

Автопроверки (preflight)

Команда validate проверяет:

• обнаружены ли сервисы;
• есть ли deploy-профиль;
• есть ли checker entrypoint;
• определён ли host-порт для сервиса;
• нет ли конфликтов портов между сервисами и портом борды;
• наличие системных команд (docker, а для helm/k3d-профиля — предупреждения про helm, kubectl, k3d).
• валидность конфигурации containerized checker-build профиля.

Поведение up по умолчанию

• сервисы сортируются в детерминированном порядке (k3d-сервисы сначала);
• перед запуском выполняется auto-cleanup по обнаруженным сервисам;
• для k3d-сервисов заранее выполняется pull базовых образов;
• если k3d-деплой падает, делается retry (--k3d-retries);
• в strict режиме падение одного сервиса прерывает запуск и откатывает уже поднятые;
• в best-effort режимe проблемные сервисы пропускаются.

Runtime-файлы

Все временные файлы создаются в:

• infra/forcad-local/.runtime/

Кэш сборки checker-артефактов:

• infra/forcad-local/.cache/checker-builds/

Там же сохраняется state.json, который используется командами status и down.

Переопределения через manifest

Если auto-discovery не хватает, в services-root можно положить файл forcad-local.json:

{
  "services": {
    "warehouse": {
      "checker_dir": "warehouse",
      "port": 31443,
      "checker_timeout": 40,
      "checker_type": "pfr",
      "places": 2,
      "profile": "helm_chart",
      "start_cmd": "bash redeploy.sh",
      "stop_cmd": "helm uninstall warehouse -n warehouse",
      "checker_build": {
        "enabled": false
      }
    },
    "archive": {
      "checker_build": {
        "enabled": true,
        "profile": "cpp-make",
        "command": "make",
        "artifacts": ["libgen"]
      }
    }
  }
}

Поля опциональны. Используй их, если сервис нестандартный или порт не удаётся вывести автоматически.

Полезные параметры

• --service <name> — выбрать конкретные сервисы (можно повторять)
• --board-port 8080 — порт борды
• --mode light|full — режим работы (light по умолчанию)
• --failure-policy strict|best-effort — остановиться при первой ошибке или пропускать упавшие сервисы
• --rollback-on-failure / --no-rollback-on-failure — откат уже поднятых сервисов при ошибке в strict режиме
• --auto-cleanup / --no-auto-cleanup — очистка прошлых запусков перед новым up
• --prewarm-k3d / --no-prewarm-k3d — предварительный pull k3d/k3s образов
• --k3d-retries — число повторов деплоя для k3d-сервисов
• --k3d-retry-delay — задержка между retry для k3d
• --image-pull-retries — число дополнительных retry на pull docker-образов
• --image-pull-retry-delay — задержка между retry pull
• --team-count 2 — число команд в runtime-конфиге
• --workers 2 — число celery worker'ов
• --cache-dir — путь к кэшу сборки checker-артефактов
• --no-fast — не использовать docker-compose-fast.yml