aggrega pull
aggrega pull разрешает все зависимости сущности Release и записывает lockfile, который фиксирует каждую зависимость на точной версии и дайджесте содержимого. Последующая команда aggrega build использует то, что зафиксировано в lockfile, проверяет это и останавливается, называя всё необходимое ей, что там не зафиксировано, — поэтому сборки воспроизводимы и могут выполняться без сети.
Всё, что потребляет сборка, фиксируется в этот единственный момент. Сущности каталога, исходные артефакты, на которые сущность Recipe направляет провайдер, и удалённые документы, которые провайдер запрашивает во время рендеринга, разрешаются одной и той же командой и записываются одной и той же записью lockfile. aggrega pull — это шаг, который обращается к сети; сборка к ней не обращается. В этом и состоит всё правило, а остальная часть этой страницы описывает то, что из него следует.
Что делает команда
aggrega pull разрешает зависимости трёх видов за один проход:
- Сущности каталога — Components, Features, Recipes, FeatureRecipes, библиотеки схем и сопоставлений, а также плагины Wasm, на которые ссылается Release, разрешаемые транзитивно (через
extends:,implements:,aggregate:, присоединения Feature и места$import:/$ref:в библиотеках) и загружаемые из реестра, если их ещё нет локально. - Исходные артефакты — удалённый
source:, на который отдельный Recipe или FeatureRecipe направляет провайдер: чарт Helm (OCI или классический HTTPS) или фрагмент Compose по HTTPS. Каждый из них загружается, кэшируется и закрепляется. - Внешние входные данные — удалённые документы, которые провайдер запрашивает у хоста во время рендеринга, например
$refв файлеvalues.schema.jsonчарта, указывающий на URL. Каждый из них загружается, сохраняется под своим дайджестом содержимого и закрепляется.
Два вида из трёх считываются из написанных вами документов. Третий — нет: внешние входные данные обнаруживаются при рендеринге сущности Release, поэтому эта команда её рендерит. Для запуска команды ничего из этого знать не нужно — раздел Как разрешение находит внешние входные данные описывает это полностью, а также во что обходится рендеринг, что происходит, если он не может завершиться, и как с этим соотносится сборка, которая сама заполняет свой lock-файл.
Сущность каталога, названная без реестра, загружается через default_registry рабочего пространства, а путь репозитория, указанный в этом значении по умолчанию, определяет, откуда она загружается. При default_registry: ghcr.io/acme сущность core/api-server загружается из ghcr.io/acme/component/core/api-server — туда, где её публикует aggrega push через то же значение по умолчанию, — и там же ищется её подпись. Путь задаёт только расположение: подпись, которую требует pull, ключи и удостоверения, которым он доверяет, и учётные данные, которые он предъявляет, — это те, что хранятся для хоста, поэтому запись registries для ghcr.io действует для всех путей на этом хосте. Lock-файл записывает такую сущность по её идентификатору, версии и дайджестам, так же как сущность, загруженную только с хоста. Написание пути описано в разделе как записывается хост реестра.
Результат записывается в <release-stem>.lock рядом с сущностью Release. Рабочее пространство, которое присоединяет плагин, возвращающий вердикт «принять или отклонить», получает в этом каталоге ещё и второй файл — запись доверия плагинам.
Pull, которому велено закреплять, записывает ещё один вид файлов. Рядом с каждым Recipe и FeatureRecipe в ваших каталогах, который импортирует файл артефакта, указывает на удалённый source:, записанный вами полностью, или читает source:, лежащий рядом, находится entity.lock с записью того, какой дайджест дало это содержимое. Эта запись — шаг автора сущности, aggrega pin, и по умолчанию pull его не выполняет: он проверяет lock каждой такой сущности на соответствие тому, что записал бы этот шаг, и останавливается там, где закрепления нет. aggrega pull --pin-sources или рабочее пространство, задающее pin_sources_at_pull: true, выполняет этот шаг вместо проверки — и тогда действие pull выходит за пределы каталога, где лежит Release, хотя написанные вами файлы сущностей никогда не перезаписываются. Раздел Lock сущности описывает этот файл, а раздел Предварительный просмотр того, что запишет pull показывает весь набор для вашего рабочего пространства до каких-либо изменений.
Pull, отклонённый из-за того, что ссылка ни во что не разрешилась, сообщает, откуда читаются локальные сущности, где бы он ни выполнялся. Отказ содержит собственное описание рабочего пространства: из каких каталогов оно читало локальные сущности и что изменить, чтобы сущность была прочитана, — это показывает примечание Откуда читаются локальные сущности, — и содержит его одинаково при запуске этой команды, сборки, которая сначала разрешает свои зависимости, инструмента pull из aggrega mcp и разрешения зависимостей в редакторе, потому что его формирует общее для всех них разрешение. Отказ инструмента pull также называет краткий и описательный коды условия, подобно тому как терминал выводит краткий код в начале отказа. Файл в этих каталогах, который объявляет apiVersion Aggrega — строку, начинающуюся без отступа с apiVersion: и значения, начинающегося с aggrega.ai/, — и который не удалось загрузить, например потому, что он не разбирается как YAML, назван в том же отказе среди файлов каталога, пропущенных при загрузке, с причиной, которую указал сам парсер: такой файл может оказаться тем, который объявляет сущность, названную ссылкой, а прочитать из него, какую сущность он объявляет, нельзя. YAML-файл, объявляющий другую apiVersion или никакой, не является документом Aggrega и там никогда не называется.
Lock-файл
Lock-файл закрепляет каждую зависимость за её URI, разрешённой версией и дайджестом содержимого. В нём есть разделы для сущностей каталога, библиотек схем и сопоставлений (каждая несёт обратные ссылки на сущности Components и Features, которые её используют), плагинов Wasm, исходных артефактов, внешних входных данных (каждый ключуется по URL и несёт плагины, которые его запросили) и самих файлов Release. Файл записывается в канонической, детерминированной форме.
Сущность записывается по тому, что несёт её публикация. Дайджест в строке сущности охватывает её документ и каждый файл, который она называет рядом с собой, — локальный source: сущности Recipe или FeatureRecipe, каждый файл, названный в $import:, entity.lock рядом с ней, каждый файл схемы, импортируемый сущностью Component или Feature, — тот же набор, который публикует aggrega push. Каждый файл вносит свой путь и свои байты, и ничто другое не вносит вклада: ни способ сжатия архива, ни метка времени, ни бит прав доступа, включая бит исполнения. Сущность, которая не называет ни одного файла, записывается как этот единственный документ. Поэтому одна и та же сущность записывает один и тот же дайджест независимо от того, прочитана ли она из вашего каталога или получена из реестра, а lock-файл, зафиксированный из одной рабочей копии, проходит проверку в другой рабочей копии того же коммита при любом umask и независимо от того, записывает ли система этой рабочей копии, какие файлы исполняемые. Чарт, отредактированный под сущностью Recipe, файл, добавленный в объявленный ею источник, и изменённый entity.lock меняют дайджест; скрипт, у которого переключился бит исполнения, и заметка рядом с сущностью, которую ничто не называет, — нет. Сущности Aggregate и Manifest, которые называет Release, записываются так же, каждая как свой единственный документ. Библиотека записывается по дайджесту своих байтов, то есть своего документа, откуда бы он ни был прочитан.
Каждая сущность Recipe и FeatureRecipe, которую привязывает Manifest, — это строка, каким бы уровнем она ни была привязана. Реализация, которую уровень name сущности Manifest выбирает для одного экземпляра или одного присоединения, получается и записывается точно так же, как реализация, которую её уровень type выбирает для каждого экземпляра типа, и referenced_from её строки называет запись, которая её привязывает, — manifest.spec.mappings.components.name.<instance> или manifest.spec.mappings.features.name.<attachment>. Сборка сверяет её с этой строкой, поэтому lock-файл, который её не записывает, останавливает сборку с указанием реализации и этой записи. Об обоих уровнях см. Плоское сопоставление URI.
Присоединения соединения являются зависимостями точно так же, как собственные присоединения компонента. Сущность Feature, которую называет присоединение на соединении, — записанное в элементе uses: компонента в Aggregate или в записи соединения в Release, — получается и записывается так же, как Feature присоединения, записанного на самом компоненте, и referenced_from её строки называет запись соединения, написанную автором, оканчивающуюся на .uses.<socket>.<alias>.features.<slot>.type. Реализация, которую Manifest привязывает к ней, — тоже строка, привязывает ли её features.type или features.name по имени присоединения, <alias>.<slot>. Сборка сверяет обе с их строками: lock-файл без одной из них останавливает сборку с указанием ссылки и запрашивающей её записи, а сущность Feature, содержимое которой изменилось после pull, останавливает её с указанием обоих дайджестов. О самом присоединении см. запись соединения в Aggregate.
База, которую расширяет сущность Component или Feature, является строкой независимо от того, ссылается ли на неё что-либо ещё. Операция pull проходит каждый extends: до конца его цепочки и записывает каждую базу под её собственным видом, а referenced_from её строки указывает на spec.extends расширяющей сущности — component(<name>:<version>).spec.extends. Сборка читает базу из этой строки, поэтому сущность Manifest сопоставляет собственный тип обёртки и не требует строки для её базы. О базе, которой нет ни в одном каталоге сущностей каталога, ни в кэше, ни в реестре, сообщается там, где объединяется цепочка, — см. An extends: chain cannot be assembled (Не удаётся собрать цепочку).
Release записывается по содержимому, а не только по имени. Всё, что запрашивает Release, — в какую версию чарта разрешается источник, какие компоненты попадают в какую границу, — разрешается из содержимого файла, поэтому release_documents записывает дайджест сущности Release и каждой сущности Release, которую она расширяет, наряду с release, где указано её имя. Если отредактировать Release после pull, следующая сборка остановится до какого-либо рендеринга, назвав отредактированный файл и предложив выполнить pull снова; простой aggrega pull --release <release> записывает правку, соблюдая все остальные закрепления. Дайджест охватывает байты файла как есть, поэтому изменение комментария или пробелов тоже учитывается — точно так же, как для Aggregate и Manifest. Файл, который Release импортирует через parameters, так не записывается.
Pull ищет маркер устаревания на каждом артефакте, подпись которого он проверяет, и сообщает, что нашёл. Маркер, собственная подпись которого проверяется по подписанту, признаваемому pull, — подписанту самого артефакта или идентичности из trusted_deprecation_identities реестра, — записывается и объявляется вместе с уровнем серьёзности и подписантом маркера. Маркер, который pull нашёл, но не смог признать, — нечитаемый, неподписанный, подписанный тем, кому политика не доверяет, или с подписью, которую не удалось проверить, — сообщается как marker present but not honored с причиной и не записывается. Поиск, который не удалось завершить, — pull не смог открыть реестр артефакта или перечень того, что к нему прикреплено, не ответил, — сообщается как marker lookup did not complete с причиной и ничего не записывает, потому что pull ничего не узнал о том, существует ли маркер. В реестре, собственная политика доверия которого требует подписи для вида артефакта и не является advisory, любой из этих двух случаев останавливает pull, а не сообщается. Артефакт без маркера не даёт ни одной строки, а там, где проверка подписей отключена — для рабочего пространства или для реестра артефакта, — маркер не ищется.
Фиксируйте <release-stem>.lock вместе с Release, как фиксируете любой манифест закреплённых зависимостей. Diff lock-файла точно показывает рецензентам, какие версии и дайджесты зависимостей изменились; изменение дайджеста библиотеки называет затронутых потребителей.
Что сделал конкретный pull — была ли каждая сущность заново получена из реестра (fetched-fresh), повторно использовала слот кеша (cache-reuse), найдена в локальном каталоге (local), предоставлена из копии внутри бинарного файла компилятора (in-binary) или была внешней (external: собственные Aggregate или Manifest сущности Release, прочитанные из файла или записи, которые называет Release, а не разрешённые как одна из её зависимостей; Aggregate, полученная pull из реестра, вместо этого имеет fetched-fresh), — это временная диагностика события pull, выводимая в stdout флагом --detail, и она никогда не записывается в lock-файл. Какой источник предоставил сущность, зависит от локального состояния машины, выполняющей pull, поэтому её сохранение нарушило бы побайтовую идентичность lock-файла на разных машинах. Она сообщает, что сделал этот pull, а это невозможно восстановить позже (заново полученная сущность кешируется при следующем запуске); для состояния разрешения зависимостей Release после pull используйте aggrega inspect.
Блокировка сущности
Сущность Recipe или FeatureRecipe может зависеть от байтов вне собственного документа: чарта или фрагмента, загруженного из удалённого source:, файла, который запись artifacts — или запись boundary.artifacts сущности Recipe — подключает через $import, или файлов source:, который указывает на каталог или файл рядом с ней. Дайджест каждого из них записывается в файл с именем entity.lock в том же каталоге, что и файл сущности. В написанный вами файл сущности никогда ничего не записывается; производные данные хранятся рядом с ним. Схема блокировки сущности описывает файл поле за полем.
Кто его записывает. Его записывает один шаг: aggrega pin, который запускает автор сущности; ему не нужна сущность Release, и он записывает все классы закреплений, которые хранит блокировка. aggrega pull --pin-sources и aggrega push --pin-sources выполняют тот же шаг от имени автора и записывают те же байты. Pull, которому не поручено закреплять, не записывает блокировку вовсе: для каждой сущности Recipe и FeatureRecipe, которую Release собирает из ваших каталогов, он сравнивает то, что записал бы шаг, с содержимым блокировки и останавливается там, где закрепление отсутствует или больше не соответствует своему входу, называя сущность, каждый вход и его класс, а также aggrega pin. Файлы локального источника сверяются со своими закреплениями как единый набор: блокировка, не содержащая ни одного из них, останавливает pull, как и файл, добавленный, изменённый или удалённый после закрепления. Ключ рабочего пространства pin_sources_at_pull делает закрепление поведением по умолчанию для каждого pull, а --pin-sources=false возвращает остановку на один запуск. Закрепление — обязанность автора, поэтому остановка при первом pull у потребителя означает, что издатель сущности её не закрепил; решение для потребителя — этот ключ, а не ручное редактирование чужого каталога. aggrega pin излагает это полностью.
Что он содержит. Три списка, каждая строка которых называет один вход:
sourceDigests— по одной строке для каждого удалённогоsource:, координаты которого вы записали полностью, без шаблона вkind,url,chart,module_subdir,versionилиref. Строка содержитkindиurlисточника, егоchartилиmodule_subdir, если они есть, версию, в которую он разрешился, — для git-источника коммит, на который указывал егоref, — и дайджест содержимого загруженного архива, а также дайджест манифеста для чарта, загруженного по OCI.artifactDigests— по одной строке для каждой записиartifactsилиboundary.artifacts, предоставленной файлом, импортированным через$import; строка называет запись и дайджест байтов файла. Записьartifactsназывается по своему ключу, а записьboundary.artifacts— какboundary/<key>, поэтому записи каждого блока под одним ключом закрепляются раздельно.localSourceDigests— по одной строке для каждого файла, которыйsource:, указывающий на каталог или файл рядом с сущностью, вносит в содержимое публикации сущности; строка называет путь файла относительно сущности и дайджест его байтов. Для такого источника ничего не загружается; его файлы хешируются в текущем виде. Источник, записанный шаблоном, вносит каждый файл в каталоге сущности, поэтому для каждого из них есть строка.
Чего он не содержит:
- Удалённый источник, координаты которого заполняются из шаблона, — например,
version, считываемая из.infra. Какой артефакт он обозначает, решает каждая сущность Release, использующая сущность, поэтому каждая версия, в которую он разрешается, закрепляется в lock-файле этой сущности Release, и рядом с сущностью о нём ничего не записывается. - Встроенная запись
artifactsилиboundary.artifacts, являющаяся частью файла сущности, и запись, взятая из ArtifactLibrary, содержимое которой закреплено версией библиотеки, записанной в lock-файле.
Сущность, которой нечего закреплять, не получает entity.lock, а шаг, запущенный для сущности, которой он больше не нужен, удаляет его.
Фиксируйте его рядом с сущностью. Все сущности Recipe и FeatureRecipe используют одно и то же имя файла, а каталог, в котором он лежит, указывает, к какой сущности он относится, поэтому блокировка перемещается вместе с этим каталогом. Она не содержит временных меток, а её строки хранятся в фиксированном порядке, поэтому шаг над неизменёнными входами оставляет её побайтно идентичной, а diff по ней называет изменившийся источник, импортированный файл или файл локального источника. Каталог содержит одну блокировку, поэтому шаг отклоняет сущность Recipe или FeatureRecipe, рядом с которой есть любая другая сущность, — у каждого вида есть собственный каталог, кроме Aggregate, Release и Manifest, — а pull, которому поручено закреплять, отклоняет такую сущность до какого-либо разрешения; правило излагается в разделе Одна сущность на каталог. Pull без закрепления ничего не записывает рядом с сущностью и не оценивает её каталог.
aggrega build сверяет с ним ваши файлы. Сборка читает блокировку и выполняет три сравнения:
- Каждый импортированный файл хешируется заново и сравнивается со своей строкой, файл
boundary.artifacts— так же, как файлartifacts. Файл, изменённый после закрепления, останавливает сборку с[CATALOG_ERROR E0026], называя артефакт так, как его называет строка, импортированный файл и оба дайджеста. - Файлы локального источника хешируются заново и сравниваются со своими строками как единый набор до того, как провайдер прочитает источник. Файл, изменённый, добавленный или удалённый после закрепления, останавливает сборку с
E0305для экземпляра компонента, которому принадлежит источник, называя каждый такой файл и оба дайджеста; файл рядом с сущностью, который источник не вносит, не сравнивается. Блокировка без строки для локального источника не оставляет ничего для сравнения, как описано в разделе A local source no longer matches the pins recorded beside its Recipe (Локальный источник больше не соответствует закреплениям рядом с его Recipe). - Каждая строка источника сравнивается с дайджестом, который lock-файл сущности Release записывает для того же источника. Расхождение останавливает сборку с
[FETCH_ERROR E0135], называя блокировку и оба дайджеста. Два файла записываются двумя разрешениями одного и того же источника — шагом закрепления и pull, — поэтому они расходятся, если эти разрешения получили разные байты или если один из файлов был отредактирован. Разные байты при одной версии — это признак того, что источник выше по цепочке переопубликовал версию.
Lock-файл, записанный до изменения, останавливает сборку первым, а pull называет файл. Lock-файл записывает сущность по тому, что она содержит, а блокировка и каждый файл, читаемый этими сравнениями, входят в это содержимое, поэтому сборка — или aggrega pull --verify, — использующая lock-файл, записанный до изменения импортированного файла, файла локального источника или самой блокировки, останавливается до выполнения любого из трёх сравнений: The lockfile no longer matches what the release resolves to (Lock-файл больше не соответствует результату разрешения релиза), называя сущность и оба дайджеста. Затем обычный aggrega pull называет файл, поскольку сверяет блокировку с тем, что записал бы шаг закрепления, и отклоняет вход, закрепление которого больше не соответствует: An entity reads an input the lock beside it records no pin for (Сущность читает вход, для которого блокировка рядом с ней не содержит закрепления).
Там, где lock-файл не содержит записи о собственном содержимом сущности, сборка сталкивается с тремя сравнениями. Сущность Recipe или FeatureRecipe, которую Manifest называет по ссылке, совпадающей с именем сущности Component или Feature, достижимой из Release, не имеет собственной записи: запись lock-файла для этой ссылки описывает Component или Feature, поэтому в lock-файле ничего не меняется при изменении файлов Recipe, и сборка и проверяющий pull сообщают об изменённом файле с указанным выше кодом. Со сравнением строки источника сборка сталкивается и тогда, когда изменилась запись source_artifacts в lock-файле, а блокировка рядом с сущностью — нет.
Как ответить на остановку. Если вы изменили импортированный файл намеренно, выполните aggrega pin для сущности: этот шаг запишет новый дайджест файла, и следующая сборка его примет. Если нет, восстановите файл. Для изменившегося локального источника годятся те же два ответа: снова закрепите сущность или восстановите файлы, которые называет остановка. Если строка источника расходится с lockfile, восстановите entity.lock из системы контроля версий или выполните aggrega pin для сущности, чтобы перезаписать его.
aggrega pull --verify тоже его проверяет. Проверяющий pull выполняет те же три сравнения над lock-файлами рядом с сущностями Recipes и FeatureRecipes, до которых сущность Release доходит в ваших каталогах, сообщает о каждом закреплении, которое отвергла бы сборка, с тем же кодом и в тех же словах, завершается с ненулевым кодом, если такое есть, и не записывает lock-файл.
Где lock-файл не сравнивается. У сущности Recipe или FeatureRecipe, разрешённой из реестра, а не из одного из ваших каталогов, нет lock-файла, который читает сборка; её источники сверяются только с lockfile сущности Release. Кроме того, источник, указанный по git ref:, записывается в lock-файл по коммиту, в который разрешился этот ref, тогда как сборка ищет закрепление источника по версии, которую называет сущность, поэтому эта строка никогда не сравнивается — ни сборкой, ни проверяющим pull. Lockfile по-прежнему закрепляет коммит, и каждая сборка проверяет по нему кэшированный архив.
Запись доверия к плагинам
Некоторые плагины, подключаемые рабочим пространством, никогда не влияют на выводимый результат. Подключение plugins.governance в роли ir-verdict или render-verdict, а также любое подключение plugins.linter возвращают вердикт «принять или отклонить» и ничего больше — ни один их байт не попадает в артефакт. Поэтому они не входят в то, что сборка воспроизводит байт в байт, и lockfile, который закрепляет именно это, — неподходящее для них место.
Вместо этого их идентичности записываются во второй фиксируемый в системе контроля версий файл: plugins-trust.yaml, рядом с lockfile. В нём по одной записи на каждый такой плагин: координата идентичности плагина, выбранная для него версия и дайджест содержимого разрешённого артефакта — а также подпись, которую pull проверил для этого артефакта, если он её проверял, и, если издатель после публикации объявил этот артефакт устаревшим, маркер, который pull нашёл и проверил. Схема записи доверия к плагинам описывает файл поле за полем.
Фиксируйте plugins-trust.yaml вместе с lockfile по той же причине, по которой фиксируете lockfile: запись, хранящуюся вне системы контроля версий, никто не может проверить, и сравнивать с ней нечему. Зафиксированная, она становится единым общим утверждением о том, в какой плагин разрешилось каждое из этих подключений, а diff по ней называет изменившуюся идентичность.
Файл появляется, только когда есть что записать. Рабочее пространство, не подключающее ни одного плагина, возвращающего вердикт, не разрешает ни одной такой идентичности, поэтому pull не записывает файл и ничего о нём не сообщает — это отсутствие, а не пропавший файл. Когда pull всё же создаёт файл, он называет созданный файл и предлагает вам зафиксировать его. Последующий pull добавляет идентичность, которой ещё нет в записи, и оставляет каждую уже записанную идентичность в точности как есть.
Каждое изменение этого файла объявляется, и ничего, кроме них. Pull, изменяющий запись, выводит по одной строке на каждую изменившуюся запись, называя плагин и вид изменения: идентичность записана впервые; идентичность принята вместо прежней (называются обе, чтобы вы видели, что подменено); к артефакту, который запись уже называет, добавлена отметка об устаревании; отметка об устаревании с него снята; подпись к нему записана или снята; либо запись удалена. Строка о создании, описанная выше, — отдельная и относится к файлу, а не к записи, поэтому первое разрешение сообщает и то и другое: этот файл новый и его нужно зафиксировать, и вот идентичности, которые он теперь содержит.
Pull, оставивший запись в точности такой, какой она была, ничего о ней не сообщает. Поэтому строка об этом файле означает, что зафиксированный файл изменился и его diff стоит прочитать, — и здесь это важнее, чем для lockfile. Всё, что закрепляет lockfile, также входит в то, что сборка воспроизводит байт в байт, поэтому у изменения там есть второе место, где оно проявится; у идентичности плагина-вердикта такого места нет. Этот файл — единственное место, где фиксируется подмена проверки.
aggrega pull --dry-run ничего из этого не объявляет, потому что ничего не изменяет. Вместо этого он перечисляет запись среди файлов, которые записал бы, как описано в разделе Предварительный просмотр того, что записал бы pull.
Отметка об устаревании добавляется к записи, которая уже есть, и это не то же самое, что её перезапись. Если издатель объявляет устаревшим плагин, которому вы уже доверяете, следующий aggrega pull записывает маркер в существующую запись этого плагина — координата, версия и дайджест не затрагиваются, потому что артефакт не изменился и ничего нового не принимается. Поэтому обычный pull может добавить блок deprecation, а изменить идентичность может только явное обновление. Маркер записывается только для артефакта, который запись уже называет, и никакой pull не отслеживает маркер, который перестали публиковать: записанный маркер исчезает только вместе с несущей его записью, то есть либо когда эта запись удаляется, либо когда явное обновление заново разрешает плагин и не находит маркера на байтах, уже записанных в записи.
Проверенная подпись записывается в запись тем же способом, и каждый pull определяет её заново. При каждом запуске pull проверяет подпись каждого из этих плагинов по политике доверия его реестра — плагин, отдаваемый реестром, каждый раз загружается по версии, поскольку его ничто не закрепляет, — и записывает проверенное в запись плагина, снова не затрагивая идентичность: режим, совпавшего подписанта и дайджест закэшированного пакета подписи — тот же signature, что содержит запись lockfile. В отличие от маркера, результат заменяет то, что было в записи, а если pull не проверил подписи — у плагина её нет и она не требуется, либо его допустил skip_signature_verification или реестр advisory, — запись не содержит подписи. Проверенный пакет подписи также кэшируется заново, а закэшированная копия, которая больше не соответствует своему дайджесту, перезаписывается. Таким образом, запись, потерявшая подпись, запись с подписью, скопированной из записи другого плагина, запись, чей закэшированный пакет подписи удалён или изменён, а также запись, удалённая или созданная до того, как подпись была записана, исправляются следующим обычным aggrega pull. Сборка проверяет каждый такой плагин по этому факту: см. Запись доверия к плагинам на странице сборки.
Разрешённая идентичность, расходящаяся с записанной, останавливает pull. Запись называет и версию, и дайджест, поэтому изменение любого из них — одно и то же событие: плагин, который был бы запущен, — не тот, для которого проверялась запись. Диагностика называет плагин, то, что содержит запись, и то, что сообщило это разрешение, сразу по обеим осям, — и pull останавливается, не трогая запись, так что проверенная идентичность остаётся для сравнения. Он останавливается при изменении одной лишь версии (повторная публикация без изменения байтов) точно так же, как при изменении одного лишь дайджеста (повторная отправка с той же версией).
aggrega pull --verify выполняет то же сравнение. Он не записывает ни одного из файлов, фиксируемых pull, поэтому ничего не принимает; он сообщает, описывают ли эти файлы по-прежнему то, что pull разрешил бы сегодня, и запись — один из них. Он также сверяет подпись каждой записи с той, которую даёт собственная проверка плагина при pull, и сообщает о записи, подпись которой pull записал бы, заменил или снял, — а также о плагине, для которого в записи нет записи, если сборка отклоняет его из-за отсутствия записанной подписи, — как описано в разделе Сравниваются записанные подписи в обоих файлах.
Чтобы принять новую идентичность, запросите её по имени: aggrega pull --upgrade --release <release> <plugin>, называя плагин так, как его называет подключение в .aggrega-config.yaml, без суффикса версии. Это заново разрешает только этот плагин и перезаписывает его запись, не затрагивая остальные закреплённые зависимости и остальные записанные идентичности, — и работает, хотя у плагина нет закрепления в lockfile, потому что именованная цель может называть и одно из этих подключений. Простой aggrega pull --upgrade, который заново разрешает все зависимости, также заново разрешает и перезаписывает все записанные идентичности. Так же поступает aggrega build --upgrade, который запускает простой pull с полным обновлением и не может назвать отдельную цель.
Чтобы удалить идентичность, тоже запросите это по имени. Отключение плагина в .aggrega-config.yaml не удаляет его запись, и это сделано намеренно: обычный aggrega pull никогда не удаляет записи. Выполните aggrega pull --upgrade --release <release> <plugin>, называя плагин так, как его называет запись, — его координатой идентичности, то есть строкой, которую выводит описанная ниже остановка, — и запись будет удалена, а остальные закреплённые зависимости и записанные идентичности останутся нетронутыми. Простой aggrega pull --upgrade удаляет все записи, которые больше не называет ни одно подключение вердикта, в том же проходе, в котором заново разрешает всё остальное.
Удаление последней записи оставляет файл на месте пустым, а не удаляет его. Пустая запись доверия ничего не содержит, поэтому ничего не закрепляет и ничего не останавливает — так же, как если бы её не было вовсе, — а сохранение файла означает, что удаление отображается в его diff как удаление.
Запись доверия, не соответствующая своей схеме, останавливает каждую команду, которая её читает, — сборку, lint в рамках релиза и pull, включая pull, которому самому нечего записывать. Опустошённая запись и повреждённая намеренно различаются: опустошение — это способ удалить последнюю запись, и опустошённая запись молчит, тогда как файл, содержимое которого больше не разбирается, — это ошибка, а не пустая запись: если читать его как пустой, усечение файла стало бы способом отключить сравнение. Восстановите его из системы контроля версий, чтобы вернуть проверенные идентичности.
Плагин, обслуживаемый из копии внутри бинарного файла компилятора, не записывается. Pull записывает то, что он получил, — загрузил из реестра или прочитал из кеша, — а из бинарного файла ничего не получается: эти байты идентифицируются версией компилятора, которая их содержит, поэтому собственного разрешения, которое можно было бы записать, у них нет. Поэтому подключение плагина, который уже содержится в бинарном файле, не создаёт для него записи. Это означает, что запись доверия касается только полученных артефактов, а не что разрешение завершилось неудачей.
Сборка, lint в рамках релиза и валидация в рамках релиза сверяют конфигурацию рабочего пространства с записью доверия. Прежде чем запустится любое из этих подключений, aggrega build, aggrega lint --release и aggrega validate --release — а также те же операции, вызываемые через aggrega serve и aggrega mcp, — сравнивают подключения, возвращающие вердикт, которые называет конфигурация, с записями, которые содержит запись доверия. Плагин, дайджест разрешённого артефакта которого не совпадает с записанным, отклоняется, а не запускается. Запись, которой не соответствует ни одно сконфигурированное подключение вердикта, останавливает запуск: проверка, которая была просмотрена и теперь отсутствует, оставляет вывод, неотличимый от вывода, одобренного этой проверкой, а именно этого читающий вывод увидеть не может. Сообщение об остановке называет плагин и предлагает два способа исправления в зависимости от того, что вы имели в виду: снова подключить плагин, если удаление было ошибкой, или выполнить явное обновление, описанное выше, если оно было намеренным, — и выводит это обновление готовым к запуску. Обратное направление — подключение, которого запись доверия ещё не содержит, — это первое обнаружение, описанное выше, и ни одно из сравнений на нём не останавливается; требование подписи — единственная проверка, которой подключение без записи не избегает. Те же три поверхности сверяют каждый плагин, который они читают из кеша, с подписью, записанной в его записи, при его загрузке, как страница сборки описывает это для сборки. Области lint для всего каталога и для одной сущности никакую запись доверия не используют.
Валидация сверяется с записью доверия, потому что выполняет те же проверки, что и сборка. aggrega validate --release доходит до каждой проверки, до которой доходит aggrega build, кроме записи артефактов, включая плагины-проверки, — именно поэтому «это проходит валидацию» означает то же, что «это собирается», — поэтому идентичность запускаемого плагина сравнивается с записью доверия точно так же, как при сборке. Другие области aggrega validate с ней не сверяются: валидация всего каталога, одной сущности или бинарного файла плагина вообще не читает подключения плагинов рабочего пространства, поэтому плагины вердикта в них не запускаются и записи доверия нечего проверять.
Сверка конфигурации с записью доверия устанавливает наличие и идентичность, и ничего сверх этого. Она устанавливает, что каждая проверка, которую называет запись, по-прежнему подключена и что каждая запускается из артефакта, записанного для неё. Она не устанавливает, что запущенная проверка вообще вернула вердикт, и один такой случай не обнаруживается нигде: подключение, function которого называет экспорт, который плагин действительно объявляет, но который не является экспортом вердикта, читаемым его сокетом, и вывод которого не содержит полей верхнего уровня вне формы, ожидаемой этим сокетом (простейший пример — пустой объект), запускается, не возвращает ничего, что можно отклонить, и пропускает сборку. Его вывод неотличим от вывода одобряющей проверки, и никакое сравнение с записью доверия не может этого заметить, потому что с записью всё в порядке: запущенный плагин — именно тот, что записан, и он просто ничего не выполнил. Два соседних случая всё же приводят к остановке, так что граница не шире, чем написано: function, называющая экспорт, который плагин не объявляет, отклоняется при загрузке плагина, а вывод, содержащий поле верхнего уровня, не объявленное формой сокета, отклоняется, а не читается как список вердиктов, который оказался пустым. Поэтому записанная идентичность сама по себе не гарантирует, что проверка что-либо оценила.
Записанный дайджест управляет плагинами, которые рабочее пространство разрешает из кеша, заполняемого aggrega pull, и ничем, что оно разрешает иным способом. Это обычный путь разрешения подключения вердикта: в lock-файле его ничто не закрепляет, поэтому его байты берутся из кеша, и именно при этом чтении разрешённый дайджест сравнивается с записанным. Плагин вердикта, который рабочее пространство разрешает иным способом, до этого чтения не доходит и регулируется тем, что регулирует фактический способ его разрешения, а не записью доверия: байты из копии внутри бинарного файла компилятора идентифицируются содержащей их версией компилятора, .wasm, лежащий рядом с сущностью каталога, — это файл в вашем собственном каталоге, явный путь в файловой системе — это путь, который вы указали, а плагин с закреплением в lock-файле регулируется этим закреплением. Другая половина сверки конфигурации с записью доверия так не ограничена: каждой записи должно по-прежнему соответствовать сконфигурированное подключение, как бы ни разрешался этот плагин. Таким образом, запись доверия устанавливает, что названные в ней проверки по-прежнему подключены, откуда бы они ни обслуживались, и устанавливает идентичность артефактов тех из них, что обслуживаются из кеша.
Соблюдение и обновление
По умолчанию aggrega pull соблюдает существующий lockfile: уже закреплённая зависимость разрешается в точно закреплённую версию (с проверкой по закреплённому дайджесту), разрешаются и добавляются только ещё не закреплённые ссылки, а закрепления ссылок, до которых сущность Release больше не доходит, удаляются. Поэтому повторный pull неизменной сущности Release ничего не меняет — он воспроизводит тот же lockfile байт в байт (включая generated_at). Добавление новой зависимости или pull после ручной правки, удалившей закрепление, разрешает только этот пробел и не трогает остальные закрепления.
Зависимость, которую повторный pull читает из кэша, записывается точно так же, как её записал pull, который её загрузил. Её строка сохраняет версию, дайджест содержимого digest и manifest_digest — последний берётся из манифеста, хранящегося в кэше рядом с содержимым, — а также signature и deprecation, проверенные тем pull в реестре. Пока сборка приняла бы строку, ничего из этого повторно не запрашивается, а --detail сообщает о такой зависимости как о cache-reuse. Поэтому повторный pull, все зависимости которого закэшированы, поверх lockfile, который записывает каждую подпись, требуемую конфигурацией доверия, и только подписи, принимаемые сборкой, записывает тот же lockfile независимо от того, доступен ли реестр.
Повторный pull снова запрашивает подпись именно там, где сборка отклонила бы строку, и таких строк два вида.
- Требуемая подпись, которую lockfile не записывает. Если конфигурация доверия требует подпись для зависимости, которую отдаёт кэш, а строка lockfile подписи не записывает — строку отредактировали, lockfile записали заново поверх кэша, заполненного более ранним pull, или требование добавили после pull, записавшего строку, — повторный pull запрашивает подпись у реестра этой зависимости по дайджесту манифеста, хранящегося рядом с ней в кэше, точно так же, как для загружаемой зависимости, и записывает проверенную подпись в строку. Именно такую строку отклоняет сборка (No verified signature is recorded for an artifact that requires one (Для артефакта, требующего подпись, не записана проверенная подпись)), поэтому повторный pull и снимает этот отказ. Реестр, не прикрепляющий подпись, или подпись, которую конфигурация доверия не принимает, останавливает повторный pull так же, как pull, загрузивший зависимость. Настройки, позволяющие pull допустить зависимость без подписи, оставляют такую строку как есть и ничего о ней не запрашивают:
skip_signature_verificationна верхнем уровне, тот же переключатель в собственной записи реестра — кроме вида, который требует политика подписи всего рабочего пространства, — и реестр, помеченныйadvisory. - Записанная подпись, которую сборка не принимает. Если строка записывает подпись, закэшированный пакет подписи которой был удалён или изменён после pull, закэшировавшего его, — или
signature, скопированную из другой строки, чей пакет цел, но создан для другого артефакта, — сборка отклоняет строку, что бы ни говорило требование подписи (A cached signature bundle does not match the digest recorded for it (Закэшированный пакет подписи не соответствует записанному для него дайджесту), A recorded signature was made for a different artifact (Записанная подпись создана для другого артефакта)). Поэтому повторный pull снова запрашивает подпись у реестра этой зависимости, что бы ни говорило требование, через ту же проверку, что и для загружаемой зависимости: проверенное заменяет подпись строки, а названный ею пакет кэшируется заново, причём закэшированная копия, больше не соответствующая своему дайджесту, перезаписывается, — так что строка и кэш содержат то, что оставил pull, загрузивший зависимость. Подпись, которую конфигурация доверия не принимает, останавливает повторный pull так же, как pull, загрузивший зависимость, как и реестр, не прикрепляющий подпись там, где она требуется. Если проверка ничего не записывает —skip_signature_verificationтам, где он применяется и ничего не запрашивает, реестр без подписи там, где она не требуется, или реестрadvisory, где ничего не проверяется, — подпись строки очищается, что сборка допускает при тех же настройках.
Строка, записанную подпись которой сборка принимает, повторно не запрашивается, как и строка без подписи, для которой ничто подписи не требует.
Зависимость, названную без реестра, в рабочем пространстве, которое теперь не указывает default_registry, запросить нельзя. Её строка была привязана к реестру pull, записавшим её подпись, а без реестра по умолчанию запрашивать некого. Если такая строка записывает подпись, которую сборка не принимает, повторный pull останавливается с собственным отказом сборки, сообщая, что не настроен реестр для повторного запроса строки, и оставляет lockfile без изменений. Исправить это можно, указав реестр, из которого пришла зависимость, как default_registry и выполнив pull снова.
Это соблюдение распространяется на то, что отдаёт реестр или кэш. Сущность, которую предоставляет локальный каталог, разрешается из этого каталога в версии, объявленной её файлом, и запись lockfile для неё при этом не учитывается. Lockfile всё равно записывает такую сущность, поэтому вы увидите её там, — но ручная правка этой записи не удерживает сущность в указанной вами версии, а следующее согласование перезапишет запись в соответствии с файлом. Чтобы изменить версию локально предоставляемой сущности, которую разрешает сущность Release, редактируйте файл каталога, а не lockfile.
Закрепление указывает байты, а не место, поэтому запись кэша, которая больше не содержит своё закрепление, пропускается, а не принимается на доверии. Сущность, отредактированная на месте — новое тело под той же version, — оставляет в кэше содержимого прежнее тело под этим именем и версией. Каталог читается первым, поэтому сущность, которую он всё ещё предоставляет, закрепляется по своему файлу, а устаревшая запись никогда не читается. Рендеринг, который pull выполняет для обнаружения внешних входных данных сущности Release, читает каждое закрепление так же, как сборка, — из каталога, содержащего закреплённые байты, — и сообщает о пропущенной записи уведомлением, которое выводит aggrega build. Если ни один каталог не предоставляет сущность, а реестр доступен, pull загружает закреплённую версию заново, перезаписывает запись и сообщает об этом в стандартный поток ошибок, называя запись и оба дайджеста:
reuse: cache entry for <name>:<version> held <digest the entry held>, not the pinned <pinned digest>; refreshed from the registry (pin unchanged)Загруженные байты проверяются по закреплению, как и любая загрузка под закреплением, поэтому реестр, отдающий под этой версией другие байты, останавливает pull, как описано ниже. Если ни один источник не содержит закреплённых байтов — ни один каталог не предоставляет сущность, запись кэша содержит другие байты, и ни один реестр не отдаёт закреплённую версию или запуск не достигает ни одного реестра, — pull и aggrega pull --verify останавливаются с E0135 — или E0133, если манифест записи кэша не тот, что закрепляет lockfile, — называя каждый прочитанный источник и его содержимое; если запуск не достиг ни одного реестра, остановка также называет шаг, который загружает закреплённую версию заново.
Чтобы обновить закреплённые версии, выполните aggrega pull --upgrade --release <release> — команда отбрасывает существующие закрепления и заново разрешает все зависимости в последние удовлетворяющие версии. Обновление — явное действие; по умолчанию закреплённая зависимость никогда не сдвигается. Это повторяет соглашение npm ci / cargo / go build (по умолчанию реализуется блокировка; обновление включается явно), и именно это делает безопасным автоматический pull в aggrega build: сборка разрешает ровно то, что закрепляет lockfile, никогда молча не меняя версию.
Эта форма без аргументов отбрасывает все записанные закрепления, поэтому перед любым действием запрашивает подтверждение. Для неинтерактивного использования ответьте заранее с помощью --yes; если стандартный ввод не является терминалом и --yes не указан, команда отказывается, а не ждёт ответа, который никто не может дать. Указание целей (aggrega pull --upgrade --release <release> <uri>) сохраняет все не названные закрепления, поэтому эта форма ничего не спрашивает. aggrega build --upgrade выполняет форму без аргументов и подчиняется тем же условиям.
Если байты закреплённой версии в реестре больше не совпадают с дайджестом, записанным в lockfile (нарушение неизменяемости на стороне источника), pull останавливается с ошибкой целостности, а не принимает изменённые байты молча, — запустите --upgrade, чтобы намеренно закрепить версию заново.
Проверка lock-файла без его записи
aggrega pull --verify --release <release> отвечает на один вопрос: изменит ли запуск aggrega pull сейчас lock-файл или запись доверия плагинам рядом с ним? Команда выполняет то же разрешение зависимостей, что и pull, сравнивает с ним lock-файл и запись и останавливается до записи всего, что фиксирует pull, — lock-файл, запись доверия плагинам и каждый entity.lock остаются без изменений. Она завершается с ненулевым кодом при отсутствии lock-файла и при любом расхождении, называя каждое из них. Маркеры устаревания не сравниваются, как описано ниже. Команда отклоняется вместе с --upgrade, вместе с --dry-run и вместе с --pin-sources при любом значении этого флага: verify не записывает отсутствующий в entity.lock пин и не останавливается из-за него, поэтому флаг ничего бы не изменил.
Она соблюдает записанные пины точно так же, как pull. Зависимость, закреплённая в lock-файле, разрешается в закреплённой версии и проверяется по закреплённому дайджесту, а сущность из локального каталога разрешается из этого каталога, как описано в разделе Соблюдение и обновление. Поэтому:
- Ссылка, реестр которой опубликовал более новую версию после pull, не считается расхождением. Pull сохранил бы её пин, поэтому lock-файл по-прежнему тот, который записал бы pull; новая версия принимается через
aggrega pull --upgrade. - Реестр, который теперь отдаёт другие байты под закреплённой версией, останавливает verify той же ошибкой целостности, что останавливает pull, вместо того чтобы сообщать об изменении как о расхождении.
- Строка lock-файла, отредактированная вручную, изменённая сущность Release и сущность, изменённая в локальном каталоге, — обо всех сообщается, поскольку каждое из них является расхождением между lock-файлом и тем, что pull разрешает сейчас.
Она читает и наполняет кэш так же, как pull. Запись, которую кэш хранит под её пином, — сущность каталога или .wasm плагина — читается оттуда без обращения к реестру, что и позволяет запускать verify в автономном режиме над рабочим пространством, которое наполнил pull с доступом к сети. Запись, которой нет в кэше, загружается так же, как её загружает pull, а запись, больше не соответствующая своему пину, обрабатывается точно так же, как её обрабатывает pull. Таким образом, verify может пополнять кэш, но никогда не сдвигает пин.
Она сравнивает записанные подписи в обоих файлах
Подпись, которую pull проверил для артефакта, входит в то, что он записывает: signature в записи lock-файла и в записи plugins-trust.yaml для плагина, подключённого в роли вердикта. Когда пины совпадают, verify сверяет каждую записанную подпись с той, которую pull записал бы сейчас, и сообщает о каждой подписи, которую pull записал бы там, где её нет, заменил бы или удалил, с ошибкой A recorded signature is not the one a pull would record (Записанная подпись не совпадает с той, которую записал бы pull). Все такие записи в любом из файлов называются за один запуск.
Какие записи lock-файла проверять, выбирает сам pull. Повторный pull запрашивает у реестра подпись записи именно в тех случаях, которые описаны в разделе Соблюдение и обновление, и verify следует тому же выбору:
- О двух случаях сообщается без обращения к реестру, потому что pull перезаписывает их независимо от ответа реестра: запись, обслуживаемая из кэша, без подписи там, где конфигурация доверия её требует, — pull записывает подпись артефакта или останавливается, если её нельзя установить, — и запись, чья записанная подпись сделана для другого артефакта, которую pull заменяет собственной подписью артефакта.
- О каждой другой записи, которую pull проверил бы заново, запрашивается реестр, потому что только ответ реестра показывает, изменил бы её pull: запись, байты которой загрузил этот verify, и запись, кэшированный пакет подписи которой удалён, нечитаем или изменён. Verify запрашивает реестр, как сделал бы pull, и сообщает о записи, если ответ записывает, заменяет или удаляет её подпись. Проверенный пакет подписи кэшируется так же, как его кэширует pull, поэтому запись, кэшированный пакет которой удалён, но реестр по-прежнему отдаёт записанную подпись, проходит проверку, а кэш остаётся восстановленным.
О записи, записанную подпись которой принимает сборка, и о записи без подписи, для которой подпись ничем не требуется, реестр не запрашивается — ни при pull, ни при verify.
Запись доверия плагинам сверяется с тем же pull. Каждый pull проверяет в реестре подпись каждого плагина, подключённого в роли вердикта, и verify делает то же самое, сообщая о записи, подпись которой эта проверка записала бы, заменила или удалила. О плагине, для которого в записи нет элемента, сообщается, если сборка отклоняет его из-за отсутствия записанной подписи, поскольку pull записывает элемент с его подписью, а до тех пор сборка отклоняет плагин. Любой другой — это первое появление, о котором verify не сообщает, как не сообщает ни о какой идентичности, которой ещё нет в записи. В автономном режиме verify не запрашивает реестр об этих плагинах, а что он сообщает вместо этого, описано в разделе Автономный режим.
Маркеры устаревания не сравниваются. Маркер, прикреплённый к артефакту после pull, — это состояние реестра, и он меняется без каких-либо изменений в рабочем пространстве; verify, падающий из-за него, проваливал бы проверку файлов, которых вы не касались. По той же причине записанный маркер лишь предупреждает сборку, а не останавливает её. Поэтому pull может записать маркер в запись, которую verify пропустил.
Предварительный просмотр того, что записал бы pull
aggrega pull --dry-run --release <release> разрешает зависимости точно так же, как обычный pull, а затем вместо записи выводит то, что было бы записано: заголовок с путём каждого файла, за которым следует содержимое, которое этот файл получил бы.
aggrega pull --dry-run --release release.yamlОн называет каждый файл, а не только lockfile. Lockfile, entity.lock рядом с каждой сущностью Recipe и FeatureRecipe, чьи записанные закрепления сдвинулись бы под --pin-sources, и запись доверия плагинов — все появляются в одном отчёте, потому что предварительный просмотр, показывающий только lockfile, внушил бы вам, что меняется только lockfile. Pull, который остановился бы на незакреплённой сущности, останавливается и под --dry-run — по той же причине: предварительный просмотр показывает то, что сделал бы pull. Файлы, которые pull оставил бы побайтово без изменений, в отчёте не появляются вовсе: имя в отчёте означает, что этот файл вот-вот изменится. Последняя строка подсчитывает их, и для рабочего пространства, которое pull не изменил бы, сообщается нулевое количество.
На диске ничего не меняется. Ни один lockfile не записывается и не создаётся, ни одна блокировка сущности не записывается и не удаляется, ни одна запись доверия не создаётся и не дополняется. Если возможность предоставляется несколькими плагинами-провайдерами и выбор между ними ничем не сделан, запуск останавливается с указанием того, что нужно предоставить, а не предлагает записать выбор в вашу конфигурацию: предварительный просмотр не редактирует файл конфигурации попутно.
Само разрешение всё равно выполняется, поэтому кэш всё равно заполняется. То, какие внешние входные данные потребляет сущность Release, определяется её рендерингом, а запуску, отказавшемуся от разрешения, было бы не о чем сообщить, поэтому --dry-run загружает и сохраняет ровно так же, как pull. Содержимое в .aggrega/cache читается только через закрепления, записанные в lockfile, поэтому его заполнение не меняет ничего из того, что разрешает сборка; то, что показывает пробный запуск, — это то, что записал бы pull.
Голый --upgrade под этим флагом ничего не спрашивает. Подтверждение существует потому, что полное обновление отбрасывает все записанные закрепления, а предварительный просмотр не отбрасывает ни одного, поэтому aggrega pull --dry-run --upgrade --release <release> — та форма, к которой стоит обратиться, когда вы хотите узнать, чего вам стоило бы обновление, и она выполняется без ответа.
Он не принимается вместе с --verify, который и так не записывает ни одного из этих файлов. В такой паре флаг ничего бы не делал, хотя выглядело бы так, будто он что-то сделал, поэтому она отклоняется, а не игнорируется.
Одно предварительный просмотр с закреплением не всегда может показать полностью, и он сообщает об этом, когда так происходит. Pull, которому велено закреплять, перезаписывает entity.lock рядом с каждой сущностью Recipe и FeatureRecipe, а затем выполняет рендеринг сущности Release, чтобы обнаружить её внешние входные данные; предварительный просмотр не трогает эти блокировки, поэтому там, где записанное в них закрепление устарело — например, вы изменили импортированный файл после его закрепления, — этот рендеринг сверяется с устаревшим дайджестом, который всё ещё записан в незаписанной блокировке, и останавливается. Всё остальное в отчёте — ровно то, что записал бы pull; неполны только закрепления внешних входных данных в показанном lockfile. Запуск сообщает об этом и в своём выводе, и в своей диагностике, а не выдаёт вам lockfile, который выглядит полным. Первое разрешение рабочего пространства не затрагивается, потому что записанного дайджеста, относительно которого что-либо могло бы устареть, ещё нет.
Композиция, которую описывают эти закрепления
Файл блокировки закрепляет то, что будет потреблять сборка этой сущности Release, поэтому разрешение строит ту же композицию, что и сборка: оно разрешает документы, применяет преобразования, объявленные подключениями рабочего пространства, и пропускает результат через проверки, которые сборка выполняет над готовым графом. Из этого следуют две вещи, и обе проявляются на проходе, который записывает файл блокировки, а не при первой сборке, которая его читает.
Композиция, отклонённая этими проверками, останавливает pull. Ребро uses:, цель которого не удовлетворяет selector: его сокета, сущность Feature, подключённая к компоненту, который её appliesTo: не допускает, и любое другое нарушение, о котором сообщают эти проверки, останавливают эту команду с той же диагностикой, которую выводит сборка тех же документов, — причём остановка называет все найденные нарушения за один запуск, а не только первое, так что один проход даёт вам весь список для исправления. Это происходит до записи, поэтому <release-stem>.lock и plugins-trust.yaml остаются в точности такими, какими были, и сущность Release, которая не соберётся, никогда не записывается как разрешённая без ошибок. Это не распространяется на подключения, возвращающие вердикт: ни одно подключение ir-verdict или render-verdict здесь не запускается, поэтому отрицательный вердикт останавливает сборку, lint или валидацию в рамках релиза, которые его вызывают, а не эту команду.
Подключение в роли, формирующей граф, запускается во время этого прохода, поэтому плагин, который не удаётся разрешить, останавливает pull. Подключение label-transform определяет метки узлов до того, как с ними что-либо сопоставляется, а подключение annotation-transform внедряет аннотации, которые разворачиваются в подключения Feature, — оба меняют содержимое графа, поэтому построение графа означает их вызов, а их вызов означает наличие собственных байтов каждого плагина. Плагин, байты которого этот проход не может получить, останавливает запуск с указанием плагина и того, что для него не удалось найти, — это тот же отказ, что и при сборке того же рабочего пространства, когда она не может их получить. Вызывается список подключений, только что разрешённый этим проходом, с настройками и файлами определений, которые файл блокировки записывает, чтобы последующая сборка могла их восстановить, поэтому оба прохода запускают одно и то же подключение на одних и тех же входных данных.
Сущность Plugin, названная шагом конвейера, которую ничто не содержит, тоже останавливает pull. Каждая сущность Plugin, названная в pipeline сущности Recipe или FeatureRecipe, разрешается вместе с другими зависимостями сущности Release — из каталога, из копии внутри бинарного файла компилятора, из кэша содержимого или из реестра, — и та, которой нет ни в одном из них, не смогла бы загрузиться и при сборке. Поэтому pull останавливается до какой-либо записи, называя сущность Plugin и сущность Recipe или FeatureRecipe, конвейер которой её называет, с тем же условием, которое сборка выдаёт при достижении этого шага (A plugin reference is not a Plugin entity (Ссылка на плагин не является сущностью Plugin)). Это верно для каждой сущности Recipe и FeatureRecipe, которую связывает Manifest, включая ту, которую ничто в этой сущности Release не подключает, поскольку каждая разрешается и закрепляется независимо от того, участвует ли она в рендеринге. Опубликуйте сущность Plugin или поместите её в каталог рядом с собранным .wasm и выполните pull снова.
Эта остановка и частичный запуск — намеренно разные исходы. Рендеринг, который не может завершиться, — тот, что описывают разделы How the resolution finds external inputs и Offline, — оставляет все закрепления зависимостей корректными, поэтому закрепления записываются, а недостача сообщается. Композиция, отклонённая проверками, — это не недостача в разрешённом: это сущность Release, которая не соберётся, поэтому для неё ничего не закрепляется и запуск останавливается.
Кэш
Загруженное содержимое хранится в .aggrega/cache и разделено на поддерево entities/ для сущностей каталога, поддерево source-artifacts/ для исходных артефактов и поддерево inputs/ для внешних входных данных, которые потребляет рендеринг. Слот сущности каталога именуется по её виду, координате и версии (поэтому сущности Component и Recipe с общими координатой и версией сохраняют два слота), слот исходного артефакта — по месту, откуда он был получен, его версии и префиксу дайджеста его содержимого, а слот внешнего входа — по дайджесту его содержимого; всё, что сборка читает из любого из них, сверяется с тем, что записано в lock-файле. Поэтому одинаковые закрепления версий используют один слот для разных Releases. Каждый слот исходного артефакта содержит авторитетный архив, заново создаваемую распаковку и небольшой файл метаданных; распаковка создаётся заново при каждом чтении, поэтому результат сборки зависит от архива и lock-файла, а не от состояния распакованных файлов.
Каждое имя, которое кэш выводит из значения, допустимо одновременно в Windows, Linux и macOS. Координата, версия, хост реестра или дайджест содержат символы, недопустимые в имени файла: / между частями координаты, : перед версией, внутри sha256: и перед портом реестра. Поэтому каждое значение — вид, координата, версия, хост реестра или дайджест — кодируется, прежде чем стать именем каталога или файла: строчная буква, цифра, ., _ и - записываются как есть, а любой другой символ записывается как escape-последовательность, начинающаяся с +. Сущность Component core/devtool/adminer:1.0.0 версии 1.0.0 — это слот entities/+zx000043omponent/core+zsdevtool+zsadminer+zx00003a1.0.0/1.0.0/, а слот, именуемый по дайджесту содержимого, — sha256+zx00003a<hex>. Прописная буква тоже экранируется, поэтому две координаты, различающиеся только регистром букв, сохраняют два слота в файловой системе, нечувствительной к регистру; у имени, которое Windows резервирует для устройства, например con, экранируется первая буква; и ни одно имя не заканчивается точкой. Два разных значения никогда не получают одно имя, а одно значение имеет одно и то же имя на любой машине. aggrega cache status перечисляет каждую запись по значениям, из которых закодированы её имена (сущность каталога — по её координате, версии и виду), а не по закодированным именам.
Запись архива сохраняет имя, данное ей издателем, поэтому в Windows запись, которую Windows не может хранить, отклоняется. Файлы, содержащиеся в архиве исходного артефакта или сущности каталога, размещаются под именами, которые даёт им архив, а не кодируются кэшем. Если распаковка выполняется в Windows, запись, содержащая часть, которую Windows не может хранить в записанном виде (имя, зарезервированное для устройства, например NUL или aux, в любом регистре и с расширением или без него, либо часть, оканчивающуюся точкой или пробелом), отклоняется с E0340 с указанием записи, и ничего из этого архива не размещается. В Linux и macOS такая запись размещается под своим именем. Запись, выходящая за пределы каталога распаковки, отклоняется на любой машине.
Слот сущности каталога является записью только вместе с её манифестом. Слот содержит содержимое, отданное реестром, и рядом с ним — манифест, описывающий это содержимое. Слот, содержащий только содержимое (загрузка, прервавшаяся между двумя записями, или файл, помещённый туда вручную), не является записью: pull и проверяющий pull повторно запрашивают его у реестра сущности, если тот доступен, а сборка, которая никогда ничего не загружает, считает сущность отсутствующей — как и pull, когда ни один реестр недоступен.
То, что попадает в кэш, проверяется по двум признакам: по форме, которую описывает собственная схема сущности, и по месту, которое кэш для неё назначает. Тело, полученное из реестра, перед кэшированием проверяется схемой своего вида (той же проверкой, что читает его обратно), поэтому опубликованная сущность или библиотека, которую отдаёт реестр и которую отклоняет её собственная схема, останавливает pull с указанием полученного, а не кэшируется, чтобы проявиться как ошибка позже. А значение, из которого строится расположение в кэше и которое поместило бы кэшированный файл не туда, куда указывает значение (версия, являющаяся путём, а не версией, путь url источника или module_subdir, выходящий выше своего места), отклоняется там, где строится расположение, с указанием недопустимого значения. Значение, записанное в Recipe или FeatureRecipe, которые вы создаёте, проверяется так же в момент построения расположения в кэше, а module_subdir git-источника — раньше, до загрузки репозитория, как описано ниже.
Git-репозиторий архивируется из собственного checkout. Для источника git-repository pull выполняет checkout репозитория на закреплённом коммите и архивирует каталог, указанный в module_subdir, или весь репозиторий. module_subdir, который в записанном виде выходит выше репозитория (../shared или ..\shared), отклоняется до загрузки репозитория с E0307 с цитированием значения, поэтому ничего за пределами checkout не читается. Символическая ссылка, закоммиченная в репозиторий, архивируется как файл или каталог, на который она указывает, если он находится внутри репозитория; сам module_subdir может быть такой ссылкой. Ссылка, ведущая за пределы репозитория, останавливает pull с E0321 с указанием ссылки и того, куда она ведёт, и ничего не кэшируется, поэтому репозиторий, из которого вы выполняете pull, не может заставить pull скопировать файл с вашей машины в артефакт. Checkout удаляется после остановки pull, поэтому сообщение называет ссылку по её месту в репозитории, а также репозиторий и ревизию, указанные источником, а не каталог, которого уже нет. Изменить ссылку — дело репозитория. Граница рабочего пространства описывает правило, которое здесь применяется.
Кэш привязан к рабочему пространству, а не к каталогу, из которого вы запустили команду, поэтому у одного рабочего пространства один кэш, и pull, запущенный из подкаталога, заполняет то же хранилище, которое читает сборка, запущенная из корня.
Pull, для которого рабочее пространство не найдено и не указано, отклоняется до какой-либо загрузки. Если корень ничем не указан и обнаружение ничего не находит (из папки, в которой вы запускаете команду, или, для Release, указанного абсолютным путём, из собственной папки этого Release), корнем стала бы эта папка, а кэш, записанный в ней, сделал бы её рабочим пространством. Поэтому pull останавливается, не записывает ни lock-файла, ни кэша и называет папку и два выхода: укажите рабочее пространство с помощью --workspace-root или AGGREGA_WORKSPACE_ROOT либо поместите в эту папку .aggrega-config.yaml с блоком workspace:. Инструмент pull в aggrega mcp, вызванный без workspace_root на сервере, запущенном без корня, отклоняется так же; в разделе Конфигурация перечислены другие команды, к которым это относится.
Сборка там, где сеть недоступна
Поскольку эта команда — единственный шаг, который обращается вовне, одного запуска с подключением достаточно, чтобы все последующие сборки стали локальными. Этот запуск записывает lock-файл и заполняет кэш рабочего пространства байтами, на которые указывают эти закрепления, и сборке после этого не нужно ничего сверх них.
На отключённую машину переносятся три вещи:
- Сущность Release и её lock-файл. Зафиксируйте
<release-stem>.lockрядом с Release: именно он сообщает сборке, к какой версии и какому дайджесту разрешилась каждая зависимость. plugins-trust.yaml, если рабочее пространство подключает плагин, возвращающий вердикт. Сборка сверяет подключения вердиктов, которые называет её конфигурация, с этой записью до запуска любого из них, поэтому именно перенос записи удерживает отключённую сборку в рамках проверенных идентичностей и подписей, которые pull для них проверил. Зафиксируйте её рядом с lock-файлом, как описано в разделе Запись доверия плагинам.- Каталог кэша. В нём хранятся сущности, исходные артефакты и закреплённые входные данные, и всё, что не предоставляет локальный каталог
catalog_dirs, читается оттуда.
На отключённой машине выполняйте сборку как обычно. Включить там автономный режим имеет смысл, даже несмотря на то, что сборка по заполненному lock-файлу читает своё замыкание из кэша: он превращает возможное обращение к сети в немедленный отказ с указанием режима, а не в попытку подключения, которая сначала должна истечь по тайм-ауту. Всё, чего нет в кэше, и любые внешние входные данные, которые lock-файл не закрепляет, останавливают сборку с указанием того, чего не хватает, и разрешения, которое бы это закрепило, — ничего не загружается втихую, чтобы заполнить пробел.
Изолированная машина и автономное рабочее пространство — разные утверждения, и это различие стоит сохранять. Машина за воздушным зазором может содержать локальную копию реестра или каталог catalog_dirs со всем необходимым, и тогда обычный pull на этой машине выполним вообще без обращения вовне. Автономный режим описывает, к чему команда может обращаться, а не то, что хранится на машине; в разделе Автономный режим изложено, от чего он отказывается и что оставляет без изменений.
Автономный режим
В автономном режиме — заданном ключом верхнего уровня offline в файле конфигурации, переменной AGGREGA_OFFLINE в окружении или флагом --offline в командной строке — aggrega pull отказывается обращаться к сети. Отказ происходит до любой попытки соединения, а не как тайм-аут посреди загрузки, поэтому автономный pull не обращается ни к одному реестру и ни к одному удалённому источнику. Если режим задан закоммиченным файлом или экспортированной переменной, а вам нужно обойти его для одной команды, --offline=false разрешает сеть только для этого запуска.
--upgrade в этом режиме отклоняется сразу, и это единственный такой параметр здесь. Полное обновление поднимает каждую зависимость до самой высокой версии, которую реестр предлагает сейчас, поэтому ему нужно спросить реестр, что тот сейчас отдаёт. Обычному pull это не нужно: он соблюдает уже записанные закрепления, разрешает только то, что их не имеет, и поэтому может быть выполнен из того, что есть на машине. Сообщение об отказе указывает, какое из трёх мест задало режим и как разрешить сеть для одного запуска.
Разрешение затем опирается только на то, что уже есть на машине: стек поиска catalog_dirs и кэш в .aggrega/cache. Если каталог и кэш удовлетворяют всем ссылкам, автономный pull завершается нормально и записывает обычный lock-файл. Lock-файл записывает для каждой зависимости URI, разрешённую версию и дайджест, но никогда не записывает, какое из этих мест отдало байты, — поэтому автономный и сетевой pull, разрешившие одни и те же версии, записывают одинаковый lock-файл.
Зависимость, которую автономный pull не может удовлетворить локально, останавливает его. Запись никогда не пропускается:
- Сущность каталога, которая нигде не разрешается, останавливает pull с указанием ссылки и места, откуда на неё сослались, так что названы и отсутствующая зависимость, и то, что её запросило.
- Удалённый
source:останавливает pull с указанием источника и предложением либо разрешить доступ к сети, либо заполнить кэш из окружения с подключением. - Зависимость, которая есть в кэше, но чью обязательную подпись lock-файл не записывает или чью записанную подпись сборка не принимает, останавливает pull с автономным отказом и указанием зависимости: чтобы записать подпись, нужно обратиться к её реестру, как описано в разделе Соблюдение и обновление. Разрешение сети для одного такого запуска записывает её. Записанная подпись, которую сборка принимает, повторно не запрашивается, поэтому автономный pull она не останавливает.
Внешний вход — единственное, что не останавливает pull; вместо этого он сообщает об этом. Рендеринг, который их находит, не может загрузить то, что ещё не сохранено, поэтому автономный pull для сущности Release с незакреплённым внешним входом завершается, записывает все разрешённые закрепления зависимостей и сообщает три вещи: что рендеринг не завершился, что он закрепил и что сборка этой сущности Release остановится с указанием URL. Записанные закрепления зависимостей верны — ничто в них не зависело от рендеринга, — поэтому они сохраняются, а не выбрасываются, чтобы читателю не пришлось воспроизводить их заново.
Это сделано намеренно, а не является пробелом, и переключателя для этого нет. Pull, отбрасывающий верную работу, лишил бы вас успешно выполненной части; pull, промолчавший об этом, выдал бы вам lock-файл, который выглядит полным, но таковым не является. Сообщить об этом — единственный исход, оставляющий вам возможность действовать: запустите pull снова из окружения с подключением или из окружения, в кэше которого уже есть это содержимое, и та же команда его закрепит.
Таким образом, автономный pull — это отказ обращаться к сети, а не урезанный результат для всего, что называет документ, а для внешних входов — это завершённое разрешение, которое сообщает, до чего оно не смогло дотянуться. Существующий lock-файл — это файл, разрешение зависимостей которого завершилось; полны ли его внешние входы, сообщает собственный вывод pull, и именно этого затем требует от него сборка.
--verify в автономном режиме проверяет меньше и сообщает об этом. Чтобы узнать, куда записанная ref источника указывает сегодня, нужно обратиться к её удалённому репозиторию, а автономный режим это запрещает. Поэтому автономный --verify проверяет закреплённые зависимости и пропускает эту ось, выводя строку об этом, а не сообщая о совпадении, которое он не установил. Записанная подпись, которую может подтвердить только её реестр, — в записи lock-файла, чей кэшированный пакет подписи был удалён или изменён, — пропускается так же, со строкой, называющей каждую такую запись:
verify: offline, so the signature the lockfile records for "<reference>" was not checked at its registry, which alone can say whether a pull would record it again; this verify does not cover itО записанной подписи, которую pull перезаписал бы при любом ответе реестра, сообщается и в автономном режиме, поскольку для этого ответ не нужен, как описано в разделе Сравниваются записанные подписи в обоих файлах.
Plugin, подключённый в роли вердикта и отдаваемый реестром, — это место, где автономные verify и pull расходятся. Такой plugin никогда не закрепляется в lock-файле, поэтому каждый pull разрешает его .wasm из его реестра, и автономный pull для рабочего пространства, подключающего такой plugin, останавливается на нём, называя его plugin, чей .wasm не удалось разрешить, — даже если кэш содержимого его содержит и независимо от того, помечен ли этот реестр как advisory или пропускает проверку подписей. Автономный verify, напротив, ничего не спрашивает у реестра о plugin: он читает plugin из кэша содержимого, как это делает сборка, и останавливается, если в кэше нет его .wasm или есть такой, который больше не совпадает с дайджестом из его опубликованного манифеста. Он по-прежнему сверяет идентичность plugin с записью доверия plugin и повторно проверяет его функции хоста по этому .wasm, останавливаясь при любом расхождении — точно так же, как verify с подключением. Он сообщает о plugin там, где pull перезаписывает его запись при любом ответе реестра, то есть там, где сборка отвергает plugin из-за его записи: за отсутствие записанной подписи — потому что его запись её не содержит или в записи доверия нет записи для него, — или потому что подпись в его записи сделана для другого артефакта, и pull заменяет её собственной подписью plugin. Любую другую запись — ту, чью подпись сборка принимает, и ту, чей кэшированный пакет подписи был удалён или изменён, — он называет в строке о том, что её подпись не проверялась, и ничего не сообщает об этой подписи:
verify: offline, so the signature of "<plugin>" was not checked at its registry, which alone can say whether a pull would record the same signature on its entry in the plugin trust record; this verify does not cover itТаким образом, автономный verify пропускает запись, чью подпись pull с подключением заменил бы или очистил, — например, запись, подписант которой был изменён вручную, или подпись, которую реестр больше не прикрепляет, — и об этом говорит только эта строка. Verify в изолированной среде остаётся доступным; он не сообщает лишь, сдвинулась ли с тех пор ref и была бы пропущенная подпись записана снова. Проверка, которая читает только код выхода, охватывает это лишь тогда, когда verify выполняется с подключением.
Интеграция с aggrega build
- Проверка.
aggrega buildпроверяет каждую разрешённую зависимость по lock-файлу и останавливается при расхождении: сущность, библиотека или плагин, содержимое которых больше не совпадает с закреплением; ссылка, до которой теперь доходит сущность Release, но которую lock-файл не закрепляет, или закреплённая ссылка, до которой сущность Release больше не доходит; а также файл сущности Release, отредактированный после pull. Чтобы устранить расхождение, выполнитеaggrega pull --release <release>— команду, которую выводит остановка: pull разрешает сущность Release в её текущем виде, переписывает сдвинувшиеся закрепления и сохраняет все остальные, так что не плавает ничего, что вы не меняли. Если сдвинулся файл в локальном источнике сущности Recipe, pull сначала называетaggrega pinдля этой сущности, как описано в разделе Блокировка сущности. Lock-файл, только что записанный этой командой, проходит эту проверку, потому что команда выполняет ту же проверку перед записью; сборка, которая останавливается на расхождении сразу после pull, получила иные входные данные, чем pull, — каталог--catalog, переданный одной команде и не переданный другой, или конфигурацию рабочего пространства, отредактированную между ними, — поэтому запускайте обе команды над одними и теми же входными данными.aggrega validate --releaseи каждый выборaggrega inspect, разрешающий сущность Release, применяют к lock-файлу ту же проверку и отказывают с той же остановкой, поэтому ни одна из них не пропускает lock-файл, который отвергает сборка. - Автоматический pull. Если lock-файл отсутствует и
auto_pullимеет значение true,aggrega buildсначала автоматически выполняет pull. Еслиauto_pullимеет значение false (по умолчанию), сборка останавливается и предлагает выполнить pull. Pull, запускаемый сборкой, следуетpin_sources_at_pull, поэтому на незакреплённой сущности он останавливается точно так же, как обычный pull. Шаг pull, запускаемый сборкой, — тот же, что описан на этой странице, поэтому сборка, заполняющая существующий lock-файл, останавливается на сдвинувшейся ссылке источника точно так же, какaggrega pull, — см. Детерминизм и целостность. - Автономный режим. В автономном режиме
aggrega buildиспользует только то, что уже есть на машине, и отказывает в доступе к сети до какой-либо попытки подключения. Ссылка, содержимого которой нет в кеше, останавливает сборку, а не приводит к сбою посреди загрузки, а сборка без lock-файла, которой не поручено его заполнить, останавливается, называя pull, который бы его заполнил, точно так же, как в сетевом режиме.--auto-pullне отклоняется: запрашиваемое им заполнение — это pull, описанный на этой странице, поэтому для сущностей каталога, уже находящихся в кеше или в локальном каталоге, он записывает lock-файл, не обращаясь к реестру, — сущность Recipe, чарт которой загружается из удалённого источника, разрешается заново, поэтому в автономном режиме она останавливает процесс, даже если чарт есть в кеше, — а ссылка, которой нет ни там, ни там, — или закешированная ссылка, требуемую подпись которой lock-файл не записывает или записанную подпись которой сборка не принимает, — останавливает его собственным отказом pull с указанием этой ссылки.--upgradeотклоняется по причине, указанной в разделе Автономный режим. - Поиск в каталогах. Pull учитывает
catalog_dirsиз.aggrega-config.yaml, даже если--catalogне указан, — а также собственные каталоги сущности Release, если конфигурация задаёт их вworkspace.releases, — и разрешает тот же стек поиска с приоритетом первого совпадения, что иaggrega build, поэтому закрепляемые им зависимости совпадают с тем, что ищет сборка. Указанный каталог, который не является каталогом, — например, там ничего не существует, — отклоняется обеими командами до того, как что-либо будет разрешено или записано, с указанием записи, а также файла конфигурации и строки, где она указана, как показано в разделе Откуда читаются локальные сущности.
Как разрешение находит внешние входные данные
Ничто в этом разделе не меняет правило выше: по-прежнему есть один момент, в который что-либо закрепляется, и это эта команда. Здесь описано, как команда добирается до третьего из трёх видов. Это важно, когда вы встраиваете разрешение в конвейер, разбираете запуск, который завершился частично, или пытаетесь понять, зачем эта команда вообще выполняет рендеринг.
Сущность каталога и исходный артефакт названы в документе, а внешние входные данные — нет. Чтобы разрешить первые две, достаточно прочитать то, что вы написали. Внешние входные данные называет провайдер в ходе рендеринга, и то, какие URL он называет, зависит от рендерируемых значений: отсутствующая запись values оставляет целое поддерево схемы чарта нескомпилированным, и ни одна удалённая ссылка в этом поддереве не запрашивается. Никакое чтение сущности Release не позволяет перечислить этот набор.
Поэтому команда делает две вещи за один проход: разрешает и закрепляет замыкание, названное в документах, а затем рендерит это замыкание, чтобы увидеть, какие удалённые документы запрашивают провайдеры. Отрендеренные артефакты отбрасываются, а закрепления сохраняются. Оба шага выполняются внутри одной команды, и ни один из них не является вторым моментом, в который что-то может быть закреплено: lockfile записывается один раз, и в нём есть все закрепления.
Прежде чем встраивать разрешение в автоматизированный конвейер как дешёвый шаг, стоит знать о двух последствиях. Оно обходится дороже, чем разрешение, которое только читает документы, потому что выполняет рендеринг. И оно может завершиться неудачей по причине, невозможной для разрешения только по документам: провайдер не может отрендерить эту сущность Release. В этом случае закрепления зависимостей всё равно записываются, потому что они никак не зависели от рендеринга, а диагностика называет остановившийся этап, то, что было закреплено, и то, что сборка остановится с указанием незакреплённого URL. Запуск не пропадает, а в разделе Offline показан тот же результат, достигнутый другим путём.
Кроме того, до какой-либо записи рендеринг проверяет lockfile тем же сравнением, которое применяет сборка. Он выполняет ту же последовательность, что и сборка, поэтому сравнивает lockfile, который эта команда собирается записать, с тем, во что разрешается сборка той же сущности Release, — точно так же, как сборка сравнивает lockfile, найденный на диске. Lockfile, отклонённый этим сравнением, не записывается — как и всё остальное, что команда записала бы после него, — и команда останавливается с сообщением о том, что разрешение и сборка расходятся во мнении, от чего зависит Release, а затем перечисляет каждую запись, названную сравнением. Ничто в ваших файлах не может к этому привести, и повторное разрешение придёт к тому же расхождению, поэтому сообщите о нём, приложив Release, а не повторяйте попытку. Это единственный сбой рендеринга, который останавливает запись, и именно поэтому сборка той же сущности Release на тех же входных данных не сообщает о дрейфе для lockfile, записанного этой командой.
Переключателя, позволяющего пропустить рендеринг, нет. Он сохранил бы в виде опции ровно ту неожиданность, которую устраняет единственный момент закрепления: Release разрешается без ошибок, а входные данные, нужные его рендерингу, остаются незакреплёнными, и это обнаруживается только во время сборки.
--auto-pull встраивает это же разрешение в сборку, и сборка выполняет рендеринг один раз. Именно рендеринг при заполнении находит и закрепляет внешние входные данные, и сборка выдаёт результат этого рендеринга, а не выполняет второй, поэтому сборка одной командой обходится в тот же рендеринг, что и обычная сборка по заполненному lockfile. В aggrega build описано, какие флаги рендеринга сборки на него влияют.
Набор определяется параметрами сущности Release — так же уже ведут себя закрепления компонентов. Изменение параметров Release между разрешением и сборкой является изменением Release, поэтому сборка останавливается на сравнении дрейфа с указанием файла ещё до того, как какой-либо рендеринг мог бы запросить незакреплённый URL; решение — эта команда. Параметры, импортированные из отдельного файла, не фиксируются по содержимому, поэтому изменение такого файла доходит до рендеринга, который останавливается с указанием незакреплённого URL — и в качестве решения тоже называет эту команду.
Детерминированность и целостность
Поле source: сущности Recipe может шаблонизировать свою версию на основе разрешённых values и infra сущности Release (а также locals, определённых в ней же); они разрешаются во время pull, и результат закрепляется. Pull вычисляет только те записи locals:, которые читают поля source:, и записи, которые читают уже они, используя исключительно собственные шаблонные функции Aggrega: запись, которую читает источник и которая вызывает функцию Sprig, останавливает pull с указанием записи, поля и функции, а запись, которую не читает ни одно поле source:, остаётся сборке, которая вычисляет и проверяет её при рендеринге сущности Recipe — см. Resolving a source: coordinate registers a narrower function set (Разрешение координаты source регистрирует более узкий набор функций). Изменяемый тег или ветка Git закрепляется на конкретном коммите, на который указывает, а заданная вами ссылка записывается рядом с ним. Во время сборки дайджест кэшированного архива повторно сверяется с lock-файлом, поэтому подменённый кэш обнаруживается.
Записанная ссылка удерживается на закреплённом ею коммите. Ссылка записывается потому, что последующие запуски снова её опрашивают, а не ради читаемости: сборка спрашивает, какой артефакт она называет, а pull — указывает ли она туда же, куда раньше. Команда pull, не являющаяся обновлением, заново опрашивает каждую записанную ссылку, и ссылка, которая сместилась в удалённом репозитории, останавливает запуск — с указанием артефакта, ссылки, коммита, закреплённого в lockfile, и коммита, в который она разрешается сейчас, — вместо того чтобы принять смещение. Чтобы принять его, выполните aggrega pull --upgrade --release <release>. Целевое обновление, в котором указываются URI сущностей, этого не делает: ссылка на источник не является сущностью, которую можно указать, поэтому целевой запуск удерживает её точно так же, как обычный pull.
Эта проверка — единственное, чего не может сделать за вас повторная сверка дайджеста во время сборки. Pull, принявший сместившуюся ссылку, одним действием перезаписал бы загруженные байты и записанный дайджест, поэтому оба значения, которые сравнивает сборка, сместились бы вместе и совпали — и вы собирали бы иное исходное содержимое, чем то, по которому проверялся lockfile, и ничто бы об этом не сообщило.
Так удерживается только ссылка, записанная в lockfile, а ссылка записывается всякий раз, когда вы её указываете. Recipe, называющий свой источник только через version:, не имеет ссылки, поэтому последующему запуску нечего опрашивать заново — и это правильно, ведь версия, которую вы написали сами, не может сместиться без вашего ведома. В справочнике по lockfile указано, что записывается.
Пишите ссылку, а не коммит. Команда build находит артефакт из git по написанной вами ссылке, сопоставляя её со ссылкой, записанной в lockfile, поэтому ref: v1.2.3 собирается на том коммите, на котором был закреплён этот тег, и коммит никогда не должен появляться в вашем Recipe. Указать изменяемый тег в version: вместо этого не получится, и так задумано: version: сопоставляется как написано, а для источника git lockfile закрепляет коммит.
Lockfile закрепляет содержимое, загруженное из реестров и удалённых источников, и записывает дайджест каждой сущности, которую разрешает из каталогов вашего каталога, — по файлу сущности и каждому файлу, который она называет рядом с собой, как описано в разделе The lockfile, — а также каждого файла Release, прочитанного при разрешении. Файлы источника, начинающегося с ./ или ../, и файл артефакта, импортируемый сущностью, также закрепляются по одному в блокировке рядом с этой сущностью, как описано в разделе The entity lock, — именно это позволяет назвать изменившийся файл; за целостность остальной части рабочего пространства между сборками отвечает система контроля версий. Область действия гарантии детерминированности см. в разделе побайтово идентичный вывод.
Аутентификация
Учётные данные реестра читаются только из конфигурации учётных данных Docker: config.json в каталоге, который указывает DOCKER_CONFIG, или ~/.docker/config.json, если эта переменная не задана, а также из любого помощника учётных данных или связки ключей ОС, которым этот файл делегирует через credsStore или credHelpers. aggrega login <registry> записывает туда учётные данные, как и docker login <registry>; выполните любую из них перед aggrega pull для закрытого каталога OCI или реестра чартов. Файлы, которые записывают podman login и helm registry login, не читаются.
Конфигурация учётных данных, которую невозможно прочитать, сообщается без её содержимого. Если config.json не является корректным JSON, значение auth записи не является закодированными в base64 пользователем и паролем, соединёнными двоеточием, или указанный в файле помощник учётных данных не может ответить, обращение к реестру завершается ошибкой с сообщением, называющим реестр и файл учётных данных, но никогда — содержимое файла или записи. aggrega login и aggrega logout так же сообщают о config.json, не являющемся корректным JSON, и ничего в нём не меняют. Исправьте файл; запись, которую невозможно прочитать, также можно заменить с помощью aggrega login <registry>.
Классический репозиторий Helm-чартов или архив чарта (helm-https-chart), фрагмент compose (compose-https-fragment) и Git-репозиторий, доступный по HTTP или HTTPS (git-repository), аутентифицируются с помощью файла netrc — пользовательского файла учётных данных, который читают также curl и Git. Это единственное хранилище учётных данных, которое читают эти три вида: ~/.config/helm/repositories.yaml и помощники учётных данных Git не читаются. Git-репозиторий, доступный по SSH, аутентифицируется через SSH-агент и не читает файл netrc.
machine charts.example.com login deploy-bot password <token>Какой файл читается. Файл, указанный переменной окружения NETRC, если она задана. Иначе — .netrc в домашнем каталоге; в Windows — _netrc в %USERPROFILE%, если этот файл существует, и .netrc там же, если нет. Отсутствующий файл не содержит учётных данных и ошибкой не является. Файл, который существует, но не читается или не соответствует формату netrc, останавливает команду с E0360, называя файл — а при ошибке формата и строку, — но никогда не его содержимое: The netrc file cannot be read (Не удаётся прочитать файл netrc). В Linux и macOS файл netrc, доступный для чтения другим пользователям машины, вызывает одно предупреждение с его именем; сделайте его доступным для чтения только вам (chmod 600).
Какая запись отвечает на запрос. Каждый запрос ищется по его хосту — имени хоста без порта, без учёта регистра — и обслуживается первой записью machine, называющей этот хост, или записью default, если такой нет. login и password записи отправляются как учётные данные базовой аутентификации HTTP, одинаково по http и https; запись, в которой нет одного из них, не отправляет ничего. Для репозитория, индекс которого размещает чарты на другом хосте, ответ определяется для каждого запроса отдельно: запрос индекса берёт запись хоста репозитория, а запрос чарта — запись хоста чарта. Запрос, отправляемый без учётных данных, должен быть доступен анонимно, а сервер, отвечающий 401 или 403, останавливает pull как неавторизованное получение, и способ исправления называет запись, которую нужно добавить, и файл, в котором она искалась.
Учётные данные нигде не записываются. Они читаются при выполнении получения и отправляются с запросом: lockfile, entity.lock рядом с сущностью Recipe, кеш источников и каждое сообщение содержат URL источника в том виде, в каком вы его написали.
URL источника не содержит учётных данных. Сущность Recipe или FeatureRecipe, в url источника которой перед хостом записан пользователь — https://user:token@charts.example.com/… или отдельно записанный токен, как в https://token@charts.example.com/…, — отклоняется с E0361 при чтении документа, до какого-либо получения: проверка сущности Recipe отклоняет её, как и каждый pull, pin и сборка, которые до неё доходят. Сообщение называет хост и никогда — учётные данные: A source URL carries a credential (URL источника содержит учётные данные). Вместо этого поместите учётные данные в запись machine файла netrc. В SSH отдельно записанный пользователь — ssh://git@github.com/… — обозначает учётную запись, а не секрет, и принимается, тогда как записанный там пароль тоже отклоняется.
Проверка читает только часть URL до хоста. Токен в строке запроса или в пути — …/index.yaml?access_token=… — не обнаруживается, поэтому не пишите его туда: URL записывается как есть в lockfile, в entity.lock и в кеш источников, включая имена каталогов кеша.
Переменные окружения
Параметры рабочего пространства, которые читает pull, можно переопределить через окружение — с приоритетом выше закоммиченной конфигурации и ниже любого флага: AGGREGA_OFFLINE (см. Автономный режим, а также --offline — флаг, стоящий выше него), AGGREGA_CATALOG_DIRS (список путей с разделителем, принятым в ОС; указывайте абсолютные пути), AGGREGA_ARTIFACT_CACHE_DIR, AGGREGA_DEFAULT_REGISTRY и AGGREGA_SKIP_SIGNATURE_VERIFICATION (с явным оповещением — везде, где pull проверил бы подпись, он выводит предупреждение о том, что проверка глобально отключена). Полный список и модель приоритетов см. в environment-variables.md.
См. также
- ./aggrega-build.md — проверяет lock-файл и автоматически выполняет pull, если это настроено.
- ./aggrega-serve.md — демон выполняет то же разрешение в
aggrega/resolveDependencies, а также внутриaggrega/buildдля запроса, полеautoPullкоторого этого требует, поэтому редактор может запустить его, не покидая сеанс; в обоих случаях оно выполняется, только когда запрос его указывает, и записывает тот же lock-файл, что и эта команда. - ./aggrega-push.md — публикует сущности каталога в реестр.
- ./aggrega-lint.md — проверка перед публикацией, предшествующая
aggrega push. - ../../architecture/13-catalog-and-registry.md — полное описание модели каталога, lock-файла и кэша.
Синтаксис
aggrega pull [<uri>...] [flags]Описание
Resolve the Release's catalog and source dependencies into the cache and write the per-Release lockfile.
By default, pull reconciles the lockfile against the current dependency resolution while honoringthe pins it already records. That pin discipline governs what a registry or the content cacheserves: such an entity is fetched at its pinned version and verified against its pinned digest,and if the registry no longer serves the pinned bytes, pull halts rather than silently re-pinning.An entity a local catalog directory supplies is resolved from that directory instead, at theversion its file declares, and its recorded pin is not consulted — so editing a pin by hand doesnot hold a locally-supplied entity at that version, and the reconcile rewrites the entry to matchthe file. A reference with no pin — newly added, or removed from the lockfile by hand — isresolved fresh and added. Entities no longer among the resolved dependencies are pruned.Re-running pull on an unchanged dependency set is a no-op.
Use --upgrade with no positional arguments to discard the existing lockfile and re-resolveevery entity from current registry state, floating each dependency to the highest availableversion. That form drops every recorded pin, so it asks for confirmation first; --yes answers inadvance, and on a non-interactive stdin it refuses rather than waiting for an answer nobody cangive. Pass one or more entity URIs after --upgrade to upgrade only those: each named pinis dropped and re-resolved fresh while every other pin — and the recorded external inputs —is held unchanged. A named target may also be a plugin that returns an accept-or-reject verdict;such a plugin carries no lockfile pin, and its identity is recorded beside the lockfile instead.Naming one the workspace still attaches adopts the identity it resolves to. Naming one theworkspace no longer attaches drops its recorded identity — the one way to clear an entry thatoutlived the attachment it was recorded for. A bare --upgrade does both for every plugin at once.A URI given without --upgrade is a usage error.
Each Recipe and FeatureRecipe this Release builds from one of your catalog directories carriesthe pins for its own inputs in the entity.lock beside it: a remote source: written out in full,a file an artifacts entry imports, and each file of a local source:. Recording them is theentity author's step, aggrega pin.By default pull records none of them, and halts on an entity whose lock is missing any, namingthe entity, each input and its class, and the command that records them. A local source's filesare held to their pins as one set: a file added, changed or removed since the pin halts the pullthe same way.Pass --pin-sources, or set pin_sources_at_pull in the workspace configuration, to have pull runthat same step instead; --pin-sources=false restores the halt for one run.
Which files of a local source directory belong to its entity was decided when the entity waspinned, by the ignore rules of the plugin that served its capability for the author, and itsentity.lock records that decision. Where the plugin this workspace binds for that capabilitydeclares different rules, pull prints a warning naming both plugins and the difference, andcarries on: the entity's files are the ones its recorded rules kept.Флаги
| Флаг | По умолчанию | Описание |
|---|---|---|
--catalog | [] | Каталог; можно указывать несколько раз. Каждый —catalog <dir> добавляется в начало стека поиска каталогов (побеждает первое совпадение): catalog_dirs рабочего пространства либо, для сущности Release, которой конфигурация рабочего пространства задаёт собственные каталоги в workspace.releases, каталоги этой сущности Release; стек завершается каталогом с именем catalog в корне рабочего пространства, если он есть. Список catalog_dirs, записанный пустым, означает, что локальный каталог не читается вовсе. |
--detail | false | Вывести для каждой разрешённой сущности, что сделал этот pull: заново загрузил из реестра, повторно использовал слот кэша, нашёл в локальном каталоге, взял из самого бинарного файла компилятора или внешний источник (собственная сущность Aggregate или Manifest сущности Release, прочитанная из файла или записи, которые указывает Release). Только stdout; в lock-файл не записывается |
--dry-run | false | Разрешить зависимости и вывести то, что записал бы этот pull, вместо записи: путь каждого файла и содержимое, которое он получил бы, выводятся в stdout, а lock-файл, entity.lock рядом с каждой сущностью Recipe и FeatureRecipe, чьи записанные закрепления изменились бы при —pin-sources, и запись доверия к плагинам остаются нетронутыми. Указываются только файлы, которые действительно изменились бы. Само разрешение выполняется точно так же, как и в обычном случае, поэтому кэш содержимого всё равно заполняется, pull, который остановился бы на незакреплённой сущности, останавливается и здесь, а —upgrade без аргументов ничего не спрашивает, потому что не сбрасывает ни одного закрепления: пробный запуск показывает именно то, что записал бы pull. Не допускается вместе с —verify, который и так ничего из этого не записывает |
--include-prerelease | false | Ещё не реализовано: принимается и игнорируется, поэтому сценарий, передающий этот флаг, продолжит работать, когда флаг начнёт действовать |
--pin-sources | false | Выполнить шаг закрепления автора сущности над сущностями Recipes и FeatureRecipes, которые собирает эта сущность Release, записывая в entity.lock рядом с каждой закрепление для каждого читаемого ею входа — удалённого источника, записанного полностью, файла, импортируемого записью artifacts, и каждого файла локального источника, — вместо остановки на сущности, lock которой их не записывает. Тот же шаг, что и aggrega pin, записывающий те же байты. Запись выполняется рядом с сущностью, поэтому шаг выполняется только там, где у сущности есть доступное для записи место: документ в одном из ваших каталогов. У сущности, разрешённой из кэша, такого места нет, и она никогда не закрепляется. Переопределяет pin_sources_at_pull рабочего пространства в обе стороны: —pin-sources закрепляет в этом запуске, а —pin-sources=false останавливает этот запуск, независимо от настройки |
--progress | false | Принудительно включить вывод хода pull, даже если stderr не является терминалом, печатая по одной простой строке на каждый завершённый шаг с указанием его времени. По умолчанию — auto: интерактивный список этапов показывается, только если stderr — терминал, интерпретирующий управляющие последовательности; терминал, который их не интерпретирует, получает те же простые строки, а перенаправленный или передаваемый по конвейеру вывод не получает ничего |
--quiet | false | Отключить вывод хода pull в stderr. Не влияет на stdout. Имеет приоритет над —progress |
--release | — | Путь к YAML-файлу сущности Release (обязательно). Относительный путь разрешается относительно каталога, в котором вы запускаете команду, а не корня рабочего пространства. Если этот каталог не входит ни в одно рабочее пространство и корень не указан, по абсолютному пути рабочее пространство находится от собственной папки сущности Release |
--upgrade | false | Заново разрешить зависимости по текущему состоянию реестра, поднимая каждую до наивысшей доступной версии. Без аргументов (без позиционных URI) отбрасывает lock-файл и заново разрешает каждую сущность, предварительно запрашивая подтверждение, поскольку сбрасывает все записанные закрепления; с одним или несколькими URI сущностей заново разрешает только их, сохраняя все остальные закрепления и записанные внешние входы без изменений, и ничего не спрашивает (взаимоисключающий с —verify) |
--verify | false | Проверить существующий lock-файл на соответствие разрешению зависимостей, которое pull выполнил бы сейчас, не записывая lock-файл, запись доверия к плагинам или какой-либо entity.lock; завершается с ненулевым кодом при расхождении или отсутствии lock-файла. Разрешение соблюдает закрепления, записанные в lock-файле, точно так же, как pull: ссылка, реестр которой после pull опубликовал более новую версию, не считается расхождением, поскольку pull сохранил бы её закрепление, а реестр, который теперь отдаёт другие байты под закреплённой версией, останавливает проверку так же, как остановил бы pull. Кэш содержимого читается и заполняется так же, как при pull: запись, которая хранится в кэше под своим закреплением, читается оттуда без обращения к реестру, отсутствующая загружается, а запись, которая больше не соответствует своему закреплению, обрабатывается точно так же, как при pull. Также сверяет entity.lock рядом с каждой сущностью Recipe и FeatureRecipe в ваших каталогах, до которых доходит Release, с тем, с чем его сравнивает сборка, и завершается с ненулевым кодом при закреплении, которое сборка отвергла бы: импортированный файл, который больше не соответствует записанному дайджесту, локальный источник, файлы которого больше не соответствуют записанным дайджестам, или закрепление источника, расходящееся с lock-файлом. Также сравнивает подпись, записанную в lock-файле для каждого артефакта, и запись доверия для каждого плагина с теми, которые pull записал бы сейчас, и завершается с ненулевым кодом там, где pull записал бы, заменил или удалил их: подпись, которую требует требование, но которая не записана, и подпись, сделанная для другого артефакта, сообщаются без обращения к реестру, поскольку pull перезаписывает их независимо от ответа; подпись, которую pull запрашивает заново и мог бы записать без изменений (артефакт был загружен или его кэшированный пакет подписи был удалён или изменён), проверяется в её реестре, а в автономном режиме остаётся непроверенной с соответствующим сообщением; каждый плагин, охваченный записью доверия, проверяется в своём реестре, как при каждом pull, кроме автономного режима, где он читается из кэша содержимого так же, как при сборке, его идентичность и функции хоста всё равно проверяются, а подпись остаётся непроверенной с соответствующим сообщением, если только сборка не отвергает его из-за отсутствия записанной подписи или подписи, сделанной для другого артефакта, — тогда об этом сообщается. Метки устаревания не сравниваются. Также сообщает версии компилятора и основных плагинов, записанные в lock-файле, — только для аудита, без сравнения с этим бинарным файлом, поэтому различие в инструментарии никогда не считается расхождением. Не допускается вместе с —pin-sources при любом его значении: проверка не записывает отсутствующее в entity.lock закрепление и не останавливается на нём, поэтому флаг ничего бы не изменил (взаимоисключающий с —upgrade) |
--yes | false | Заранее ответить на запрос подтверждения —upgrade без аргументов для неинтерактивного использования. Действует только на этот запрос и ни на что иное: все остальные формы pull ничего не спрашивают, поэтому там этот флаг поведения не меняет |