Конвейер компиляции (общий обзор)
В этой главе подробно описывается внутренняя физика компилятора Go: как абстрактный YAML преобразуется в физические конфигурации на протяжении конвейера компиляции, графа промежуточного представления (Intermediate Representation, IR) и сокетов выполнения WebAssembly (Wasm).
Конвейер компиляции и поток выполнения
Aggrega выполняет строгий конвейер компилятора с фиксированным порядком, работающий заранее (Ahead-of-Time, AOT), а не жёстко заданную логику оркестрации. Запускаемый командой aggrega build, компилятор передаёт плоский граф между изолированными сокетами WebAssembly (Wasm), чтобы оценить архитектуру перед рендерингом физических артефактов.
Сокеты Wasm работают на встроенном хосте — инструментарии Extism поверх движка Wazero — за брандмауэром AOT-чистоты, который запрещает плагину любые возможности доступа во время выполнения (сеть, файловая система, системные часы, окружение, стандартный ввод-вывод), так что плагин не может нарушить детерминированную гарантию, действующую заранее. Хост запускает линтер публикации вне основного потока, через aggrega lint. Встроенные в поток шлюзы, описанные ниже, — роль преобразования меток сокета управления при построении топологии и его роль вердикта по IR при статическом анализе, а также конвейер плагинов, завершающий рендеринг, — выполняются в каждой сборке: роль управления — везде, где рабочее пространство присоединяет к ней плагин, а конвейер плагинов — для каждой сущности Recipe, которая объявляет шаги. Состояние языка отслеживает статус каждой фазы конвейера.
Конвейер выполняется полностью в памяти в строгом фиксированном порядке:
Разрешение — резолвер и синтаксический валидатор
- Механизм: слияние наследования, интерполяция шаблонов Go и валидация по JSON Schema 2020-12.
- Действие: CLI получает все запрошенные сущности (Components, Features, Releases). Сначала он проверяет эти определения на наличие ключевого слова
extends. Для сущностей каталога он выполняет глубокое слияние метаданных YAML, и два вида расходятся в отношении столпов данных:schema:сущности Feature компонуется со схемой её базы по правилам композиции JSON Schema 2020-12, тогда как расширяющий Component компонует только структуру — свои слоты прикреплений, топологические сокеты, разрешённый список самовнедрения и именованные утверждения — и получает блокschema:своей базы в точности таким, каким его написал автор базы. РасширяющийReleaseсворачивается по тому же правилу: значение потомка побеждает ключ за ключом, вплоть до первого неделимого значения — скаляра, списка, шаблона, — которое заменяется целиком, а ключ, который потомок записывает какnull, удаляется. Таким образом переносится вся его авторская поверхность — дерево границ сinfraдля каждого компонента и прикреплениями Feature, блокparameters, аннотации и указатель на Manifest, — но не переносится ни одно полеmetadata, поскольку идентичность и происхождение относятся к каждому Release отдельно. Затем он выполняет интерполяцию в памяти в три подшага: валидация контракта параметров по типизированным объявлениямparameters:сущности Aggregate; интерполяция разрешённых значений в окружающие строкиvalues:; изъятие карты.parametersиз каждого контекста шаблонов значений, после чего она остаётся доступной для чтения только шаблонам путей, написанным оператором. Наконец, он внедряет разрешённые блокиinfraв полезные нагрузки целевых компонентов. Как только схема полностью конкретизирована, компилятор использует единое объявлениеschema:из каталога (компактная форма или полная JSON Schema 2020-12), чтобы локально строго проверить конфигурацииvaluesиinfraразработчика.- Валидация схем Feature из Release: Features, прикреплённые через Release (как для всей границы, так и для конкретного компонента), на этом шаге разрешаются по своим сущностям каталога. Компилятор проверяет предоставленные в Release блоки
infraпо объявлениюschema:каждой Feature сразу после разрешения каталога, обеспечивая типобезопасность до построения топологии. - Подфаза расширения Feature на основе аннотаций: После разрешения Manifest, привязки Recipe/Provider и валидации целей привязки Manifest (пути, объявленные в
mappings.features.annotations.<key>.maps, существуют вspec.schemaуказанной Feature) компилятор выполняет подфазу расширения аннотаций перед построителем топологии. Подфаза обходит границы Release снаружи внутрь и подсистемы Aggregate снаружи внутрь, вычисляя эффективный набор аннотаций для каждого компонента через слияние с каскадом, переопределением и отказом через null; разбирает каждое значение аннотации как YAML в скаляр, структурированное значение или null; направляет каждое значение (скалярное или структурированное по подключам) через объявлениеmapsпривязки Manifest к целевому столпу схемы Feature с контролем соответствия стороны и столпа (сторона Aggregate задействуетmaps.values; сторона Release задействуетmaps.infra); проверяет типы каждого листа поspec.schemaсущности Feature; и внедряет синтетические прикрепления Feature, которые граф IR помечает какorigin: annotation. Схемы компилируются один раз за сборку и повторно используются при обходах каскада. Расширение выполняется после валидации целей привязки и перед построением топологии, поэтому последующие этапы обрабатывают синтетические прикрепления структурно идентично явным (кроме как через проверку происхождения). См. 13-catalog-and-registry.md §«Расширение Feature на основе аннотаций» иlanguage-reference/providers/well-known-annotations.mdо форме привязки, семантике каскада и правилах композиции между сторонами.
- Валидация схем Feature из Release: Features, прикреплённые через Release (как для всей границы, так и для конкретного компонента), на этом шаге разрешаются по своим сущностям каталога. Компилятор проверяет предоставленные в Release блоки
Построение топологии — построитель топологии и шлюз мутаций
- Механизм: расширение AST + роль
label-transformсокета управления. - Действие: Компилятор нативно считывает явно объявленные блоки
usesиз провалидированных компонентов, чтобы детерминированно провести топологические рёбра между узлами графа, оставляя блокvaluesполностью непрозрачным. Затем он вычисляет шлюз мутаций, передавая проекцию графа — метки каждого узла иvalues, объявленные его экземпляром, которые компилятор передаёт, не читая, — вместе с именем и окружением сущности Release плагину управления, прикреплённому к ролиlabel-transform. Плагин оценивает контекст и возвращает операции JSONPatch для динамической автоматической разметки графа (например, внедряя меткуcompliance.aggrega.ai/data-class: restrictedна основе окружения сущности Release илиdatastore.aggrega.ai/engine: vectorна основе объявленных расширений базы данных); патчи затрагивают только метки.
Финализация графа
- Механизм: нормализация.
- Действие: Компилятор финализирует плоский граф промежуточного представления (IR), сохраняя явные топологические рёбра, проведённые построителем топологии. Затем он нормализует прикреплённые Features и их полезные нагрузки
valuesв плоский словарь, индексированный по ID узла, подготавливая граф, агностичный по отношению к возможностям, к валидации.- Нормализация полезной нагрузки IR: Структурная форма IR обеспечивает единый источник истины для конфигурации: слой топологии несёт только структуру графа (идентичность узлов, рёбра, метки метаданных), а нормализованное состояние конфигурации находится в отдельном словаре в памяти, который компилятор передаёт последующим плагинам. Мутаторы, изменяющие конфигурацию, изменяют её в одном месте; провайдер читает нормализованное состояние без риска расхождения из-за избыточного хранения.
Статический анализ — статический анализатор и шлюз валидации
- Механизм: проверки топологической чистоты + роль
ir-verdictсокета управления. - Действие: Компилятор выполняет абстрактный статический анализ графа IR. Во-первых, он извлекает строки
selectorиз определенийusesSchemaи вычисляет их с помощью нативного механизма сопоставления меток на Go (поддерживающего семантику в стиле Kubernetes:AND,ORчерезin()иNOTчерез!=) по явно определённым рёбрам графа, чтобы гарантировать типобезопасность между узлами для объявленных сокетов. У ребра на ad-hoc сокете — таком, который назвал автор Aggregate и не объявил каталог, — нет записи в каталоге и, следовательно, нет селектора, поэтому этой проверке нечего вычислять и ничего не упущено; каждое ребро фиксирует, к какому из двух видов оно относится, а то, что может нести ad-hoc ребро, вместо этого ограничено объявленнымprovidesцели. Он также вычисляет селекторыappliesToиappliesToAnyOfсущностей Feature, чтобы проверить, что прикреплённые функции совместимы с метками целевого компонента, а собственныйselectorкаждого заполненного слота прикрепления — по меткам Feature, которая его заполняет. Во-вторых, он вычисляет каждое требование присутствия, которое объявляет Component узла, — каждую аннотациюfeatures.aggrega.ai/requiredType.<label>— по итоговому набору прикреплений этого узла. Эта проверка выполняется в анализаторе, потому что это первый этап, который располагает обеими половинами правила: аннотациями разрешённой сущности Component и набором прикреплений, созданным 5-уровневым каскадом, с одинаковым учётом прикреплений к Aggregate, к подсистеме, к Release и полученных расширением аннотаций. Требование, которому не удовлетворяет ни одно прикрепление, останавливает сборку; требование с некорректным объявлением останавливает сборку с отдельной диагностикой, так что сломанное объявление никогда не воспринимается как выполненное требование. В-третьих, он выполняет шлюз валидации, передавая полную структуру графа (включая все узлы, рёбра, прикреплённые функции и заранее вычисленные пути DFS) плагину управления, прикреплённому к ролиir-verdict. Пользовательская Wasm-политика предприятия оценивает топологию. Если Wasm-плагин возвращает массив ошибок (например, обнаружив непрерывный путь от узлаpublicк узлуrestrictedбез определённой функции прокси), сборка останавливается.
Рендеринг
- Механизм: перехват перед рендерингом (
injectMapping), позднее связывание (valuesMapping) и сокеты рендеринга Wasm (pipeline). - Действие: Финальная фаза генерации артефактов разделена на строгие временные подфазы, которые выполняются в фиксированном порядке, что сохраняет детерминированность выполнения:
- Сопоставление внедрения (перехват перед рендерингом): Компилятор Go разрешает абстрактный контракт
.context.injectразработчика. Затем он выполняет шаблоны GoinjectMappingиз всех прикреплённыхFeatureRecipesв строгом порядке выполнения 5-уровневой «луковичной» модели (вложенный Aggregate — сначала собственные прикрепления компонента модуля, затем те, что объявляют подсистемы его модуля, снаружи внутрь → компонент корневого Aggregate → подсистема корневого Aggregate → граница Release снаружи внутрь → конкретный компонент в Release). Компилятор нативно выполняет глубокое слияние полученных словарей поверх канала памяти.context.injectвызывающей стороны. Это безопасно переписывает переменные окружения и строки подключения для вызывающей стороны ещё до того, как их увидит базовая Recipe. Сопоставление может переписать то, что доставил собственный блокinject:вызывающей стороны или одно из её подключений; ключ, который уже доставила другая прикреплённая Feature — через собственное сопоставление или собственный блокinject:, — останавливает сборку с указанием обоих прикреплений, так что порядок выполнения никогда не выбирает между значениями двух прикреплений. - Преамбула locals: Прежде чем выполнится любой шаблон
provides, компилятор вычисляет записи.localsсущности Recipe в порядке их написания, каждую в самодостаточном локальном для узла контексте —.context.instance_id,.values,.infraи уже разрешённые записи того же блока, но не.context.injectили.context.uses. Поэтому запись может читать соседнюю запись, определённую выше, и получает её разрешённое значение; авторский порядок является частью контракта везде, где одна запись читает другую, и блок никогда не переупорядочивается, чтобы ссылка разрешилась. Именно предварительное разрешение locals позволяет шаблонуprovidesчитать.locals. Шаблон.sourceсущности Recipe вычисляется в том же контексте после разрешения этих locals, что сохраняет.localsпереиспользуемым сокращением во всех шаблонах Recipe и позволяет авторам параметризовать.source(версию чарта, путь, реестр) для каждой границы. - Базовый рендеринг (
valuesMappingбазовой Recipe): Компилятор вычисляет шаблонvaluesMappingбазовой Recipe. Шаблон читает перехваченные строки из канала.context.inject(переписанные во время сопоставления внедрения), а полученный словарь значений передаётся провайдеру, которого называетcapabilityэтой Recipe, — провайдеры helm и helm-chart оба рендерят через Helm, — для рендеринга базовых артефактов инфраструктуры. - Разбор и валидация Workload: Для Recipe, объявляющей
workload:— содержимое встроенного блока илиworkload: { $import: <path> }, указывающее на файл, — этот документ вычисляется как шаблон в контексте рендеринга узла, затем разбирается как YAML в форму Workload и проверяется: отрендеренные байты проверяются по схеме Workload, декодированное значение также проверяется по ней (байты несут ключи, которые декодирование отбрасывает, а декодирование опускает поле, заданное пустым, поэтому каждая проверка отклоняет то, чего не видит другая), каждая записьattachmentsпроверяется по слотам, которые объявляетfeaturesSchemaпривязанного Component, а каждая ссылка на ресурс проверяется по разрешённомуprovidesслота, который она называет. Сбой на этом шаге останавливает сборку. Разобранный Workload помещается в контекст шаблона как.workload, чтобы шаблон, вычисляемый позже на том же узле, мог его прочитать. - Вычисление артефактов: Каждая запись, которую Recipe объявляет в
artifacts:— встроенное содержимое или файл, указанный собственным$import:этой записи, — считывается, разбирается как шаблон, вычисляется в полном контексте шаблона и несёт сведения о происхождении сборки. Полученная проекция передаётся провайдеру, который определяет формат вывода, место, куда попадают сведения о происхождении, путь вывода и итоговые байты. Каждый сгенерированный файл фиксирует, из какой авторской формы он получен, так что при коллизии имён файлов можно назвать каждого участника. - Синтез Workload: Разобранный Workload передаётся провайдеру, которого называет
capabilityэтой Recipe, и тот преобразует его в собственные ресурсы этого провайдера. У Recipe, не объявляющейworkload:, здесь нечего синтезировать; её файлы вместо этого получаются из рендеринга источника. - Рендеринг Feature (генерация ресурсов FeatureRecipe): Каждое прикрепление на узле, привязанная FeatureRecipe которого несёт собственные
source,workload,artifactsи/илиvaluesMapping, — шаблон генерации ресурсов, применяемый для вспомогательных манифестов, таких как ServiceMonitor, NetworkPolicy, ConfigMap для sidecar или ресурс доставки учётных данных, — вычисляется за один проход в том же порядке 5-уровневой «луковичной» модели, которому следует сопоставление внедрения. Существует одна последовательность по одному набору прикреплений: операционная Feature и Feature учётных данных проходят один и тот же путь, а различается между ними лишь то, что генерирует их FeatureRecipe. Для каждого прикрепления.valuesи.infraзаменяются значениями его собственной области; оно наследует вычисленные.localsбазовой Recipe;.attachment_nameназывает рендерируемый экземпляр, а.providesнесёт собственные разрешённые provides прикрепления — тот же набор, который читает потребитель. Полученный словарь значений передаётся провайдеру, названному собственной capability этой FeatureRecipe, а отрендеренные файлы добавляются в вывод границы с двумя координатами — компонентом, к которому прикреплена Feature, и затем именем, под которым она прикреплена, — так что одно имя Feature, прикреплённое к нескольким компонентам, сохраняет каждое прикрепление отдельно. Какую форму принимают эти координаты, следует из собственной раскладки хост-провайдера: каталог<component>--<instance>/рядом с собственным каталогом компонента там, где цель даёт каждому участнику собственную позицию, и префикс имени файла<component>--<instance>--там, где она читает только файлы, лежащие непосредственно в каталоге. FeatureRecipes только для внедрения — те, что несут лишьinjectMapping, уже обработанный при сопоставлении внедрения, — здесь пропускаются. Как и предшествующие подфазы, рендеринг функций выполняется по одному компоненту за раз, поэтому прикрепление обычно вычисляется сразу после компонента, к которому оно прикреплено. Прикрепление, FeatureRecipe которого объявляетreadsCallerRenderFacts: trueилиreadsTargetRenderFacts: true, вместо этого вычисляется после того, как отрендерены все компоненты и все прикрепления, не объявляющие ни того, ни другого, — так что к этому моменту отрендерен каждый компонент, подключающийся к его хосту, и каждый, к которому подключён его хост, — и его вывод попадает туда же, куда попал бы в ином случае. - Конвейер плагинов (выполнение шагов Wasm): Компилятор читает массив
pipelineсущности Recipe и выполняет его шаги в объявленном порядке. Он вызывает указанный в каждом шаге Wasm-плагин над отрендеренными документами узла, применяет возвращённые шагом операции JSON Patch по RFC 6902 к документам, к которым эти операции обращаются, и выпускает побочные эффекты шага рядом с ними — это поверхность для точечных мутаций, таких как внедрение sidecar Envoy или монтирование VolumeMount секрета. Шаг, шлюзwhen:которого рендерится в ложное значение, пропускается как сквозной, оставляя набор документов неизменным для следующего шага. URIpluginкаждого шага ещё до выполнения разрешается в проверенные байты артефакта, которые lockfile закрепляет по дайджесту. Шагиpipelineсущности FeatureRecipe выполняются так же — над собственными отрендеренными документами прикрепления, а для прикрепления в области компонента — также над документами хост-компонента.
- Сопоставление внедрения (перехват перед рендерингом): Компилятор Go разрешает абстрактный контракт
Все три вида входных данных Recipe доходят до компилятора: source: + valuesMapping: — через базовый рендеринг, workload: — через разбор и синтез рабочей нагрузки, а artifacts: — через вычисление артефактов. Какие из них можно передать данному провайдеру, решается не отдельно на каждом подэтапе — это устанавливается один раз для каждого узла, до любой отправки на рендеринг, на основании собственного объявленного контракта провайдера, так что Recipe, вид входных данных которой привязанный провайдер не принимает, отклоняется там, а не на полпути рендеринга. См. 16-recipe-input-composition.md о модели композиции трёх видов входных данных, виде Workload и механизме артефактов, а также Состояние языка о том, какой провайдер принимает какой вид.
Вывод, нативный для GitOps
Чтобы оставаться строго без собственного мнения в отношении того, как применяется его вывод, плагины рендеринга выводят сгенерированные артефакты в чистую структуру каталогов, изолированную по границам (например, dist/boundaries/aws-core-cluster/, dist/boundaries/gcp-data-cluster/). Это позволяет внешним контроллерам GitOps (например, ArgoCD или Flux) синхронизировать и применять инфраструктуру, при этом компилятору Aggrega никогда не нужны учётные данные API работающего кластера.
graph TD
subgraph CLI_Orchestrator ["The Aggrega Compiler Pipeline"]
direction TB
A["Resolution — The Resolver & Syntax Validator<br/>(Inheritance Merge + Parameter Interpolation + JSON Schema 2020-12 Validation)"] --> B["Topology construction — The Topology Builder<br/>(AST Expansion + governance label-transform)"]
B -->|"Emits IR Graph"| C["Graph finalization<br/>(Normalization)"]
C -->|"Flat IR Graph"| D["Static analysis — The Static Analyzer<br/>(Selectors + governance ir-verdict Gate)"]
D -->|"Validated Topology"| E["Rendering<br/>Inject mapping: Pre-Render Interception (injectMapping)<br/>Base rendering (valuesMapping)<br/>The plugin pipeline: Wasm Mutation (pipeline)"]
end
graph LR
E["Rendering"]
E -->|"Stringified Artifacts"| F["Helm Charts"]
E -->|"Stringified Artifacts"| G["Docker Compose"]
E -->|"Stringified Artifacts"| H["Kubernetes Manifests"]
E -->|"Stringified Artifacts"| I["Terraform Configuration"]
E -->|"Stringified Artifacts"| J["CloudFormation Templates"]
Карта исходников инфраструктуры
Aggrega компилирует Aggregate.yaml длиной около 30 строк в тысячи строк физической конфигурации JSON или YAML. Без способа проследить работающий ресурс до его источника отладка сбоя в «main.tf.json, строка 4 032» вынуждает разработчиков восстанавливать соответствие вручную. Плагины рендеринга Aggrega решают эту задачу, сливая идентификаторы трассировки с нативной поверхностью метаданных провайдера — metadata.labels и metadata.annotations для Kubernetes, комментарием о происхождении для Terraform и эквивалентными соглашениями для каждого провайдера, — так что каждый отрендеренный объект несёт указатель на источник, из которого он получен. Метка aggrega.ai/compiler-version (описана в governance-and-compliance §5) — один из ключей трассировки в этом семействе; рядом с ней штамп несёт aggrega.ai/aggregate-name, aggrega.ai/component-id, aggrega.ai/boundary-path, aggrega.ai/recipe-uri и aggrega.ai/environment, и его выводит каждый из провайдеров helm, helm-chart, compose, terraform и cloudformation — провайдер helm-chart в файлах шаблонов, которые сущность Recipe добавляет в чарт, поскольку собственные шаблоны чарта он копирует без изменений.
Штамп не несёт ключа, указывающего происхождение функции или тип каталога.
Вместе с компилятором поставляются ещё два средства отладки. aggrega build --trace записывает промежуточное состояние каждого узла, проход за проходом, в .trace/ рядом с dist/ — для автора сущности Recipe, изучающего, что получил и что произвёл каждый этап; а останавливающая диагностика несёт категорию поверхности авторинга, к которой она относится, — DEVELOPER_ERROR, OPS_ERROR, CATALOG_ERROR и остальные, — везде, где у сбоя она есть, поэтому указывает на нужного автора. Ошибки, прослеживающие сбойное поле сгенерированного манифеста до строки шаблона, которая его породила, не входят в компилятор.
Конвейер валидаторов
Фаза валидации схем при разрешении опирается на конвейер валидаторов, который преобразует содержимое спецификаций сущностей (компактная форма, JSON Schema в YAML или смешанный вариант) в единый документ JSON Schema 2020-12 с происхождением для каждого листа, а затем валидирует по нему содержимое экземпляров, написанное разработчиками. Пять этапов выполняются по порядку как чистые преобразования; каждый является детерминированной функцией своих объявленных входных данных.
Этап 1 — Компиляция компактной формы. Компилятор обходит YAML-дерево содержимого schema:, parameters: и SchemaLibrary; выполняет диспетчеризацию по узлам (лист компактной формы, JSON Schema в YAML, ссылка $ref: или композиция); выдаёт разрешённую JSON Schema 2020-12. Компактная форма и JSON Schema в YAML могут смешиваться на любой границе узла через экранирование $jsonschema:; смешанный случай компилятор обрабатывает, обходя дерево и выполняя диспетчеризацию по узлам. Преобразование является чистой функцией: один и тот же вход в компактной форме всегда даёт один и тот же выход JSON Schema. Словарь ключевых слов см. в language-reference/vocabulary/compact-form-authoring.md.
Этап 2 — Разрешение spec.templates и $instantiate:. Для записей SchemaLibrary, написанных как ссылки на шаблоны, компилятор обходит каждую запись библиотеки, вызывающую $instantiate: с $args:, подставляет значения параметров как замену литеральных скаляров и создаёт конкретные записи схемы. Подстановка выполняется один раз на каждую загрузку библиотеки; разрешённые записи кешируются. Форму, в которой пишется сущность библиотеки, см. в language-reference/entities/schemalibrary.md.
Этап 3 — Раскрытие $ref: между документами. Для ссылок на SchemaLibrary через $ref: (форма идентичности <Library>#/schemas/<entry>) компилятор обходит цепочку ссылок во время компиляции, передавая стек разрешения; содержимое, на которое ссылаются, встраивается в схему потребителя. Раскрытие сохраняет обнаружение циклов (циклы останавливают сборку с ошибкой, называющей цепочку), защиту «идентичность, а не расположение» (ссылка, содержащая хост реестра, останавливает сборку с подсказкой использовать форму идентичности — ссылки адресуют библиотеки по идентичности, а не по физическому расположению) и композицию из одного источника (блоки $ref: принимают только голую ссылку; переопределения на стороне потребителя компонуются через allOf: из JSON Schema). Семантику разрешения см. в language-reference/vocabulary/cross-document-ref.md.
Этап 4 — Синтез моста для featuresSchema:. Компилятор обходит содержимое featuresSchema: каждой сущности в порядке автора и выдаёт фрагмент JSON Schema, описывающий форму заполнения, которое может связать каждый слот присоединения, с ключевым словом расширения x-aggrega-inject: на слоте, объявляющем список разрешённых inject. Этот фрагмент компилируется и проверяется отдельно, по написанному блоку присоединений, а не встраивается в содержимое schema:, предназначенное для разработчика; ключевое слово расширения — это метаданные, которые валидация JSON Schema игнорирует, и ни один последующий этап не считывает его обратно из фрагмента — проверка, которой нужен список разрешённых для слота, читает сам слот. Таблица сокетов usesSchema: не проецируется ни в какой фрагмент: selector: и inject: сокета читаются как типизированный YAML, написанный архитектором, а valueSchema: / infraSchema: сокета для каждого ребра компилируется отдельно. Синтез является чистой функцией своих входных данных.
Этап 5 — Собственный механизм слияния с происхождением. Для сущностей, объявляющих extends:, компилятор обходит цепочку родителей; разрешённая JSON Schema родителя становится основой; переопределения потомка применяются поверх неё. Каждый лист в разрешённой схеме несёт тег происхождения (путь к файлу, номер строки, происхождение от родителя или потомка). Выход механизма слияния — это то, что потребляет движок валидатора; движок валидатора — это немодифицированная сторонняя реализация, совместимая с JSON Schema 2020-12, обёрнутая детерминированным обходчиком для упорядоченной выдачи результатов.
Пять этапов выполняются до того, как движок валидатора увидит схему. Движок получает один разрешённый документ JSON Schema 2020-12 и содержимое экземпляра от разработчика; он создаёт отчёт о валидации. Форматировщик ошибок обращается к тегам происхождения, чтобы выдавать диагностику для пользователя, чётко называющую позиции в исходниках, — включая исходный файл для ограничения, которое сущность Feature унаследовала от своей основы, а не написала сама.
Конвейер валидатора выполняется там, где каждая полезная нагрузка впервые становится полной, — для values и infra компонента во время разрешения, для компонентов вложенного агрегата, когда построение топологии их подключает, и для полезной нагрузки присоединения при финализации графа, — поэтому замечание схемы останавливает сборку до того, как статический анализ вычислит какой-либо селектор, и до вычисления утверждений, что позволяет шаблонам утверждений опираться на провалидированные полезные нагрузки.
Сохранение детерминизма на всём конвейере
Каждый этап конвейера компиляции сохраняет инвариант детерминированного вывода: при тех же исходных файлах, том же lockfile и той же версии компилятора сборка даёт побайтово идентичный вывод. Инвариант является основополагающим — адресация по содержимому в lockfile требует стабильных дайджестов артефактов; воспроизводимые сборки требуют, чтобы релиз, написанный на ноутбуке разработчика A, компилировался в тот же вывод на ноутбуке разработчика B и в CI; возможность рецензировать диффы требует, чтобы изменения исходников были единственными изменениями в скомпилированном выводе.
Детерминизм сохраняется благодаря небольшому числу дисциплин, которые соблюдает каждое преобразование:
- Фиксированный порядок итерации. Каждый обход YAML в форме словаря итерирует в фиксированном порядке, поскольку нативная итерация словарей в Go рандомизирована. На большинстве этапов компилятор сортирует перед итерацией (компилятор компактной формы, механизм слияния, разрешатель
spec.templates, форматировщик ошибок, сериализатор YAML); проекция слотов присоединения, напротив, сохраняет порядок автора, так что порядок свойств таблицы слотов — это порядок, в котором она написана. - Без встраивания времени. Компиляция не встраивает временные метки в вывод. Сборка в 14:00 даёт тот же артефакт, что и сборка в 2:00. Метаданные происхождения механизма слияния используют файл:строка, а не файл:временная метка.
- Пути относительно рабочего пространства. Все пути в разрешённом выводе относительны рабочему пространству; слой разрешения путей нормализует их до того, как они попадут в какой-либо вывод.
- Никаких случайных источников и внешнего состояния. Преобразования являются чистыми функциями своих объявленных входных данных (содержимое сущности, цепочка родителей, lockfile). К внешнему состоянию обращаются только во время разрешения (получение артефактов OCI), а разрешённое содержимое адресуется по содержимому через дайджест.
- Каноническая сериализация YAML. Для одного входа вывод записывается в одной фиксированной форме: одинаковый порядок ключей на каждом уровне вложенности при каждом запуске, при этом массивы и массивы
enum:сохраняют порядок ввода; отступ в 2 пробела; окончания строк Unix LF; строки без кавычек, где это допускает YAML; булева формаtrue/false; null опускается для отсутствующих полей. - Алфавитный порядок
$defs:. Записи$defs:схемы выдаются в алфавитном порядке ключей в разрешённой JSON Schema.$defs:концептуально является словарём, а не упорядоченным списком; алфавитный порядок делает диффы предсказуемыми при реорганизациях исходников. - Параллелизм не проявляется в выводе. Компилятор может распараллеливать независимые единицы (разные сущности могут компилироваться параллельно). Параллельные результаты собираются в детерминированную структуру (например, отсортированную по имени сущности) перед сериализацией.
Сквозные тесты компилятора компилируют каждую фикстуру несколько раз в рамках одного теста и проверяют, что каждый запуск выдаёт одни и те же файлы с побайтно идентичным содержимым. Именно повторная компиляция выявляет утечку порядка итерации словаря или итерацию по неотсортированному множеству, которые в большинстве запусков дают стабильный вывод и лишь изредка расходятся. Эти тесты выполняются вместе с остальным набором тестов компилятора.
Инвариант детерминированного вывода действует во время сборки: те же исходные файлы + тот же lockfile + та же версия компилятора дают побайтово идентичный вывод. Сопутствующее свойство во время блокировки (те же исходные файлы + то же состояние реестра дают тот же lockfile) слабее — реестры изменяемы (могут публиковаться новые версии; могут добавляться sidecar-файлы; метаданные отдельных компонентов могут меняться), поэтому два вызова блокировки для одних и тех же исходных файлов в разное время могут дать разные lockfile. В этом и состоит назначение lockfile, как и в соглашениях npm, Cargo и Go. Из свежего lockfile сборка даёт детерминированный вывод. Разделение этих двух моментов и делает изменяемость на стороне реестра приемлемой: sidecar, опубликованный в момент T2, меняет следующий вызов блокировки; он не меняет сборки по lockfile, сгенерированному в момент T1.