Импорт документов

Обзор

И определения тестов, и конфиги нагрузки принимают верхнеуровневый ключ import:, указывающий базовый документ. База загружается первой — рекурсивно, у неё может быть своя база, — затем импортирующий документ deep-merge'ится поверх. Команда держит одну выверенную базу (профиль нагрузки, переменные, SLO-гейты), а каждый сервис переопределяет только то, что отличается.

# perf/config/_base.yaml — владеет платформенная команда
vus: 50
duration: 5m
variables:
  region: eu-west
  base_url: https://staging.example.com

# services/checkout/perf.yaml — владеет команда checkout
import: ../../perf/config/_base.yaml
variables:
  base_url: https://checkout.staging.example.com   # region наследуется

Импорты — часть open-source движка и работают одинаково для -f test.yaml и -c config.yaml.

Семантика слияния

• Объекты сливаются по ключам, рекурсивно — variables: обоих документов объединяются; одноимённые ключи выигрывает импортирующая сторона.
• Всё остальное заменяется — скаляры и массивы, включая steps:. Документ с собственным steps: целиком заменяет список базы; документ без него наследует шаги базы как есть.
• Цепочки работают (A импортирует B, B импортирует C); циклы падают с печатью всей цепочки.

Валидация выполняется над слитым документом: perfscale lint и perfscale run сначала разрешают импорты, так что ошибки указывают на то, что реально выполнится.

Формы источника

# 1. относительный путь — от каталога импортирующего файла
import: ../shared/_base.yaml

# 2. сырой HTTP(S) URL — ref зафиксирован в пути
import: "https://raw.githubusercontent.com/org/repo/v1.2.0/perf/config/_base.yaml"

# 3. файл на ref любого git-хоста (SSH или HTTPS, включая self-hosted)
import:
  git: git@gitlab.example.com:group/repo.git
  ref: v1.2.0          # тег, ветка или SHA коммита
  file: perf/config/_base.yaml

Git-импорты выполняются через системный git (clone --depth 1), поэтому SSH-ключи, credential-хелперы и настройки прокси работают как обычно — приватные репозитории доступны с той же аутентификацией, что и у git clone.

Безопасность: сетевые импорты — только по явному разрешению

Разрешение импортов происходит на этапе загрузки конфига — до гейтов allow_file_actions / allow_process_actions. Сетевой import: внутри недоверенного конфига (например, файла из PR) — это SSRF-примитив и supply-chain-вектор: удалённая база может притащить allow_process_actions: true плюс шаг std/child_process@v1.

Поэтому право на сеть даёт вызывающий, а не документ:

perfscale run -f t.yaml -c c.yaml --allow-remote-import
perfscale lint c.yaml --allow-remote-import

Без флага URL- и git-импорты падают закрыто, с объяснением. YAML-поля для включения сети намеренно нет — документ не может выписать сам себе право на сеть.

Источники изолированы: документ с URL разрешает относительные импорты относительно своего URL; документ из git-репозитория может импортировать только файлы внутри того же клона (побеги через ../ отклоняются). Удалённый документ никогда не читает локальную файловую систему.

Кэширование

Git-клоны кэшируются в ~/.cache/perfscale/imports/<hash(git+ref)>:

Вид ref	Поведение
SHA коммита	Иммутабелен — кэш навсегда, никогда не перекачивается
Тег	Считается иммутабельным — кэш навсегда; --refresh-imports перекачивает
Ветка	Ревалидация через git ls-remote после TTL в 5 минут — ref: main следует за веткой, а не «застывает» на первом фетче

--refresh-imports форсирует проверку немедленно. HTTP-импорты качаются на каждый прогон — для воспроизводимости закрепляйте тег или SHA в URL.

Поддержка в редакторе

Сгенерированные JSON-схемы включают свойство import, поэтому любой редактор с # yaml-language-server: $schema=… его автодополняет. YAML-workbench платформы предлагает обе формы: import (путь/URL) и import (git ref).

Дальше

• OSS-гайд по импортам — полный справочник, включая правила изоляции источников и лимиты.
• examples/import/ — готовая пара база + переопределение.
• Setup и teardown — блоки before:/after:, которые обычно живут в общей базе.