Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Схема Aggrega Entity Lock

Сгенерированный справочник. Не редактируйте вручную — сгенерируйте заново из опубликованной JSON Schema.

Идентификатор схемы: https://aggrega.ai/schemas/entity-lock-v1beta1.schema.json

Файл entity.lock, который лежит рядом с сущностью и фиксирует закрепления содержимого для входных данных, к которым сущность обращается за пределами собственного документа: файлов, импортируемых её артефактами, файлов локального источника и удалённых источников, идентичность которых сущность записывает полностью, — а для локального источника, являющегося каталогом, ещё и правил, определивших, какие из его файлов принадлежат сущности. Записывает его один шаг: aggrega pin, который запускает автор сущности и которому не нужна сущность Release. aggrega pull и aggrega push выполняют тот же шаг и записывают те же байты, когда их об этом просят — с --pin-sources или с параметром рабочего пространства pin_sources_at_pull или pin_sources_at_push. Pull, которого не просили закреплять, здесь ничего не записывает: для сущности в собственных каталогах каталога рабочего пространства он сравнивает то, что зафиксировал бы шаг, с содержимым файла и останавливается, указывая на aggrega pin, если закрепление отсутствует или больше не соответствует своим входным данным, — для локального источника файл, добавленный, изменённый или удалённый после закрепления, останавливает pull так же, как любое другое устаревшее закрепление. aggrega build считывает его обратно и останавливается, если дайджест того, что находится на диске, больше не совпадает с записанным. Его область действия определяется каталогом, в котором он лежит, — он закрепляет входные данные сущности в этом каталоге, — поэтому одно имя файла подходит для всех видов, а не каждый вид имеет собственное написание. Шаг удаляет lock-файл сущности, которая не читает таких входных данных, а не оставляет пустой. Сам документ сущности никогда не пишется машиной: то, что ввёл автор, остаётся в точности как введено, а то, что вывела машина, находится здесь. Именно это разделение делает lock-файл безопасным для коммита и читаемым в виде diff, поскольку каждая строка называет одни входные данные, а изменившийся дайджест указывает на изменившиеся входные данные. Он не содержит меток времени и метаданных разрешения, поэтому повторный запуск шага над неизменёнными входными данными оставляет файл побайтно идентичным. Одна форма строки служит всем видам, которые могут фиксировать закрепление, поэтому закрепление читается одинаково, к какому бы виду оно ни относилось. Формат передачи закрыт (additionalProperties: false). Дисциплина развития схемы: добавление нового необязательного поля — изменение SemVer-MINOR (аддитивное); удаление поля или ужесточение ограничения — SemVer-MAJOR.

Тип верхнего уровня: object

Свойства

СвойствоТипОбязательноОписание
versionconst 1даВерсия схемы entity-lock: 1. Изменение схемы уровня SemVer-MAJOR увеличивает её. Константа: 1
sourceDigestsobject[]нетЗакрепления содержимого для удалённых источников, на которые ссылается эта сущность и идентичность которых сущность записывает полностью; фиксируются при разрешении по полученным байтам и считываются при сборке, чтобы убедиться, что кэшированный источник не изменился. Каждая запись повторяет идентичность разрешённого источника {kind, url, chart, moduleSubdir, version} и добавляет дайджест содержимого (а для источника, распространяемого через OCI, — дайджест манифеста). Источник, идентичность которого заполняется из шаблона — например, версия, считываемая из инфраструктурных значений сущности Release, — здесь записи не имеет: какой артефакт он называет, решает каждая сущность Release, использующая эту сущность, поэтому каждая идентичность, в которую он разрешается, закрепляется вместо этого в lock-файле этой сущности Release. Локальный (заданный относительно файловой системы) источник здесь тоже записи не имеет: он называет путь, а не что-то получаемое, поэтому закреплять полученный архив нечего, и вместо этого его файлы закрепляются по отдельности в localSourceDigests.
artifactDigestsobject[]нетЗакрепления содержимого для файлов, которые артефакты этой сущности импортируют через $import (для сущности Recipe — также файлов, которые импортируют её записи boundary.artifacts); фиксируются при разрешении и считываются при сборке, чтобы убедиться, что импортированный файл не изменился. Одна запись на каждый артефакт, значением которого является импорт файла; встроенный (литеральный) артефакт уже является частью сущности и отдельного закрепления не имеет, а артефакт, взятый из библиотеки, закрепляется версией, в которую разрешилась эта библиотека. Сборка сравнивает запись любого из блоков с её закреплением одинаково и отклоняет файл, который ему больше не соответствует, при одном и том же условии.
localSourceDigestsobject[]нетЗакрепления содержимого для файлов локального источника этой сущности — источника, записанного как путь рядом с сущностью, а не получаемого извне; фиксируются при закреплении сущности и считываются при сборке, чтобы убедиться, что файлы не изменились. Одна запись на каждый файл, который источник вносит в содержимое публикации сущности: каждый файл в каталоге, названном источником, который оставляют правила, записанные в ignore, либо единственный файл, который он называет. Локальный источник, записанный как шаблон, называет свой каталог только после того, как сущность Release заполнит шаблон, поэтому он вносит каждый файл в собственном каталоге сущности, который оставляют записанные правила, и каждый из них закрепляется. Документ сущности, файл автора .aggregaignore рядом с ним и этот файл никогда не становятся записями: документ — это сама сущность, правила ignore-файла записаны в ignore, а lock-файл не может записать собственный дайджест. Как только lock-файл записывает здесь хотя бы одну запись, сборка отклоняет источник, содержащий файл без записи, файл, содержимое которого больше не соответствует дайджесту его записи, или источник, в котором нет файла, названного записью.
ignoreobjectнетПравила, определяющие, какие файлы в каталоге локального источника этой сущности принадлежат ей; записываются при закреплении сущности. Каждое последующее чтение этого каталога применяет эти правила и ничего больше: публикация сущности, сравнение, которому pull или публикация подвергают lock-файл, строка сущности у автора, сравнение и рендеринг при сборке, а также проверяющий pull. Поэтому изменение файла автора .aggregaignore, привязки провайдера в рабочем пространстве или бинарного файла aggrega не меняет ни одного дайджеста, пока сущность не будет закреплена заново, а повторное закрепление показывает это изменение здесь в виде diff. Присутствует, только если сущность объявляет локальный источник, являющийся каталогом или записанный как шаблон. Lock-файл, не записывающий правил, оставляет все файлы в этом каталоге. Символическая ссылка в любом месте внутри него отклоняется, а не разыменовывается.

Дополнительные свойства не допускаются.

entity-lock.sourceDigests[]

СвойствоТипОбязательноОписание
kindenumдаВид разрешённого источника. Одно из значений закрытого набора — того же набора, что несут kind артефакта-источника в lock-файле и kind в метаданных кэша, — поскольку все три записывают одни и те же идентичности разрешённых источников, а сборка считывает вид, чтобы выбрать загрузчик. terraform-module-oci входит в этот набор, но ни один адаптер источников его не обслуживает: Recipe или FeatureRecipe, который его указывает, отклоняется при чтении. Допустимые значения: "helm-oci-chart", "helm-https-chart", "compose-https-fragment", "git-repository", "terraform-module-oci"
urlstringдаURL источника, заданный автором, который закрепляет дайджест, — URL идентичности в том виде, как он записан в spec.source.url (корень репозитория или прямая ссылка на .tgz для helm-https-chart). Сборка восстанавливает этот же URL офлайн, поэтому он является стабильной идентичностью, по которой индексируется закрепление, а не расположением разрешённого артефакта.
chartstringнетИмя чарта для helm-источника с корнем репозитория (spec.source.chart), часть идентичности разрешённого источника, чтобы два чарта, обслуживаемые из одного корня репозитория в одной версии, закреплялись раздельно. Отсутствует для прямой ссылки на .tgz, а также для источников OCI, compose и git, ни один из которых не выбирает чарт внутри URL.
moduleSubdirstringнетКаталог внутри репозитория из git, который является артефактом (spec.source.module_subdir), часть идентичности разрешённого источника, чтобы два каталога одного репозитория на одном коммите закреплялись раздельно. Отсутствует, когда артефактом является весь репозиторий, а также для любого вида, который получает свой артефакт по URL, а не спускаясь внутрь клона.
versionstringдаКонкретная закреплённая версия, в которую разрешился источник: версия чарта для вида helm-*, коммит, в который разрешилась ссылка git-repository. Записывается как один сегмент пути, поскольку из неё строится слот кэша, из которого сборка считывает источник, поэтому она не содержит /, \ и ... Шаблон: ^([^/\\.]|\.[^/\\.])*\.?$.
digeststringдаДайджест содержимого полученного архива источника в формате sha256:, за которым следуют 64 шестнадцатеричных символа в нижнем регистре; проверяется по кэшированным байтам при сборке. Шаблон: ^sha256:[a-f0-9]{64}$.
manifestDigeststringнетДайджест манифеста OCI для источника, распространяемого через OCI, — независимый корень доверия — в формате sha256:, за которым следуют 64 шестнадцатеричных символа в нижнем регистре. Присутствует только для источника OCI (helm-oci-chart); отсутствует для источника https или git, у которого манифеста нет по построению. Шаблон: ^sha256:[a-f0-9]{64}$.

Дополнительные свойства не допускаются.

entity-lock.artifactDigests[]

СвойствоТипОбязательноОписание
namestringдаФайл $import какого артефакта закрепляет эта запись: ключ карты artifacts: для записи из artifacts и boundary/, за которым следует ключ, для записи из boundary.artifacts сущности Recipe, — поэтому записи обоих блоков под одним ключом закрепляются раздельно.
digeststringдаДайджест содержимого байтов импортированного файла в формате sha256:, за которым следуют 64 шестнадцатеричных символа в нижнем регистре; проверяется при сборке. Шаблон: ^sha256:[a-f0-9]{64}$.

Дополнительные свойства не допускаются.

entity-lock.localSourceDigests[]

СвойствоТипОбязательноОписание
pathstringдаПуть к файлу относительно каталога, содержащего документ сущности, записанный с прямыми косыми чертами, например charts/app/templates/deployment.yaml.
digeststringдаДайджест содержимого байтов файла в формате sha256:, за которым следуют 64 шестнадцатеричных символа в нижнем регистре; проверяется при сборке. Шаблон: ^sha256:[a-f0-9]{64}$.

Дополнительные свойства не допускаются.

entity-lock.ignore

Правила, определяющие, какие файлы в каталоге локального источника этой сущности принадлежат ей; записываются при закреплении сущности. Каждое последующее чтение этого каталога применяет эти правила и ничего больше: публикация сущности, сравнение, которому pull или публикация подвергают lock-файл, строка сущности у автора, сравнение и рендеринг при сборке, а также проверяющий pull. Поэтому изменение файла автора .aggregaignore, привязки провайдера в рабочем пространстве или бинарного файла aggrega не меняет ни одного дайджеста, пока сущность не будет закреплена заново, а повторное закрепление показывает это изменение здесь в виде diff. Присутствует, только если сущность объявляет локальный источник, являющийся каталогом или записанный как шаблон. Lock-файл, не записывающий правил, оставляет все файлы в этом каталоге. Символическая ссылка в любом месте внутри него отклоняется, а не разыменовывается.

СвойствоТипОбязательноОписание
pluginobjectнетПлагин, который обслуживал возможность сущности в рабочем пространстве автора в момент закрепления сущности, — привязка провайдера этой возможности в рабочем пространстве или, если её нет, плагин, встроенный в бинарный файл aggrega, — названный без версии, и объявленные им правила игнорирования. Ни версия, ни дайджест плагина не записываются: каждое чтение применяет именно правила, поэтому повторное закрепление под другим выпуском того же плагина оставляет lock-файл неизменным, если правила не изменились. Если собственный плагин pull для этой возможности объявляет другие правила, pull сообщает об этом в информационном предупреждении, называя оба плагина и различие, и никогда не останавливается из-за этого. Отсутствует, если возможность не обслуживал ни один плагин.
rulesobject[]нетТочные составные правила в порядке их применения: шаблоны плагина, затем строки каждого найденного при обходе файла игнорирования из тех, что называет плагин (собственный файл каталога — раньше файлов в его подкаталогах), затем строки файла .aggregaignore автора рядом с сущностью. Более позднее совпадение переопределяет более раннее, поэтому за файлом автора остаётся последнее слово для любого пути, который он называет, а строка, начинающаяся с !, возвращает то, что исключило более раннее правило. В каталог, исключённый правилом, обход не заходит, поэтому файл в нём возвращается только тогда, когда возвращается сам каталог.

Дополнительные свойства не допускаются.

entity-lock.ignore.plugin

Плагин, который обслуживал возможность сущности в рабочем пространстве автора в момент закрепления сущности, — привязка провайдера этой возможности в рабочем пространстве или, если её нет, плагин, встроенный в бинарный файл aggrega, — названный без версии, и объявленные им правила игнорирования. Ни версия, ни дайджест плагина не записываются: каждое чтение применяет именно правила, поэтому повторное закрепление под другим выпуском того же плагина оставляет lock-файл неизменным, если правила не изменились. Если собственный плагин pull для этой возможности объявляет другие правила, pull сообщает об этом в информационном предупреждении, называя оба плагина и различие, и никогда не останавливается из-за этого. Отсутствует, если возможность не обслуживал ни один плагин.

СвойствоТипОбязательноОписание
namestringдаПлагин, который обслуживал возможность сущности в момент её закрепления, в виде <pluginType>/<name>, без версии: чтение применяет приведённые ниже правила, а имя говорит, чьими они были. Длина не менее 1 символа.
patternsstring[]нетШаблоны игнорирования, объявленные плагином, в том виде, в каком он их объявил.
filesstring[]нетИмена файлов игнорирования, которые, по объявлению плагина, его экосистема учитывает внутри источника.

Дополнительные свойства не допускаются.

entity-lock.ignore.rules[]
СвойствоТипОбязательноОписание
patternstringдаОдин шаблон игнорирования в синтаксисе gitignore.
withinstringдаКаталог, к которому относится шаблон, относительно каталога с документом сущности, записанный с прямыми слешами; . обозначает сам этот каталог. Шаблон, объявленный плагином, относится к каталогу локального источника, строка файла игнорирования — к каталогу, содержащему этот файл, а строка файла .aggregaignore автора — к каталогу сущности.
fromstringдаГде был объявлен шаблон: plugin для шаблона, объявленного плагином, а в остальных случаях — путь к файлу игнорирования, из которого он прочитан, относительно каталога с документом сущности.

Дополнительные свойства не допускаются.