aggrega pull
aggrega pull розв’язує всі залежності сутності Release і записує lockfile, який закріплює кожну залежність за точною версією та дайджестом вмісту. Наступна команда aggrega build використовує те, що закріплено в lockfile, перевіряє це й зупиняється, називаючи все потрібне їй, що там не закріплено, — тож збірки відтворювані та можуть виконуватися офлайн.
Усе, що споживає збірка, закріплюється в цей один момент. Сутності каталогу, вихідні артефакти, на які сутність Recipe спрямовує provider, і віддалені документи, які provider запитує під час рендерингу, розв’язуються тією самою командою й записуються одним і тим самим записом 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, і саме тому ця команда його рендерить. Для запуску команди нічого з цього не потрібно — розділ Як розв’язання знаходить зовнішні вхідні дані описує це повністю, а також те, чого коштує рендеринг, що стається, коли його не вдається завершити, і як із цим пов’язана збірка, що сама заповнює свій lockfile.
Сутність каталогу, названа без реєстру, завантажується через default_registry робочого простору, а шлях до репозиторію, який містить цей типовий реєстр, і є місцем, звідки її завантажують. З default_registry: ghcr.io/acme сутність core/api-server завантажується з ghcr.io/acme/component/core/api-server — куди її публікує aggrega push через той самий типовий реєстр, — і там же шукається її підпис. Шлях визначає лише розташування: підпис, якого вимагає pull, ключі й ідентичності, яким він довіряє, і облікові дані, які він подає, — це ті, що зберігаються для хоста, тож запис registries для ghcr.io керує всіма шляхами на цьому хості. Lockfile записує таку сутність за її ідентичністю, версією та дайджестами, так само як сутність, завантажену лише з хоста. Як записувати шлях, описано в розділі як записується хост реєстру.
Результат записується у файл <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 і там ніколи не називається.
Lockfile
Lockfile фіксує кожну залежність за її URI, розв’язаною версією та дайджестом вмісту. Він має розділи для сутностей каталогу, бібліотек схем і відображень (кожна з них містить зворотні посилання на сутності Components і Features, що її використовують), Wasm-плагінів, вихідних артефактів, зовнішніх вхідних даних (кожен запис має ключ за URL і містить плагіни, які його запитали) та самих файлів Release. Файл записується в канонічній, детермінованій формі.
Сутність записується за тим, що містить її публікація. Дайджест у рядку сутності охоплює її документ і кожен файл, який вона називає поруч із собою, — локальний source: сутності Recipe або FeatureRecipe, кожен файл, який називає $import:, entity.lock поруч із нею, кожен файл схеми, який імпортує Component або Feature, — той самий набір, який публікує aggrega push. Кожен файл додає свій шлях і свої байти, і ніщо інше не додається: ні спосіб стиснення архіву, ні позначка часу, ні біт дозволу, зокрема біт виконання. Сутність, яка не називає жодного файлу, записується як цей єдиний документ. Тож та сама сутність записує той самий дайджест, чи її прочитано з вашого каталогу, чи завантажено з реєстру, а lockfile, закомічений з одного checkout, проходить перевірку на іншому checkout того самого коміту незалежно від його umask і від того, чи записує система цього checkout, які файли є виконуваними. Чарт, відредагований у сутності 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>. Збірка звіряє її з цим рядком, тож lockfile, який її не записує, зупиняє збірку з назвою реалізації та цього запису. Про два рівні див. Пласке відображення URI.
Приєднання з’єднання є залежностями так само, як власні приєднання компонента. Сутність Feature, яку називає приєднання на з’єднанні, — записане в записі uses: компонента в Aggregate або в записі з’єднання в Release, — отримується й записується так само, як Feature приєднання, записаного на самому компоненті, і referenced_from її рядка називає запис з’єднання, який написав автор, із закінченням .uses.<socket>.<alias>.features.<slot>.type. Реалізація, яку Manifest прив’язує до нього, теж є рядком, чи прив’язує її features.type, чи features.name з ключем за назвою приєднання, <alias>.<slot>. Збірка звіряє обидві з їхніми рядками: lockfile без одного з них зупиняє збірку з назвою посилання та запису, що його запитує, а сутність 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 lockfile точно показує рецензентам, які версії та дайджести залежностей змінилися; зміна дайджесту бібліотеки називає споживачів, яких вона зачіпає.
Що зробив певний pull — чи кожну сутність щойно завантажено з реєстру (fetched-fresh), повторно використано слот кешу (cache-reuse), знайдено в локальному каталозі (local), надано з копії всередині бінарного файлу компілятора (in-binary), чи вона була зовнішньою (external: власні Aggregate або Manifest сутності Release, прочитані з файлу чи запису, який називає Release, а не розв’язані як одна з її залежностей; Aggregate, яку pull завантажив із реєстру, натомість є fetched-fresh), — це тимчасова діагностика події pull, яку --detail виводить у stdout, і вона ніколи не записується в lockfile. Яке джерело надало сутність, залежить від локального стану машини, що виконує pull, тож її збереження порушило б побайтову ідентичність lockfile між машинами. Вона повідомляє, що зробив цей 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, — тож вони розходяться, коли ці розв’язання отримали різні байти або коли один із файлів було відредаговано. Різні байти під однією версією — це ознака того, що upstream повторно опублікував версію.
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 теж його перевіряє. Перевірне отримання виконує ті самі три порівняння для блокувань поруч зі сутностями Recipes і FeatureRecipes, до яких сутність Release доходить у ваших каталогах, повідомляє про кожне закріплення, яке відхилила б збірка, з тим самим кодом і тими самими словами, завершується з ненульовим кодом, якщо таке є, і не записує жодного блокування.
Де блокування не порівнюється. Сутність Recipe або FeatureRecipe, отримана з реєстру, а не з одного з ваших каталогів, не має блокування, яке читала б збірка; її джерела звіряються лише з lockfile сутності Release. А джерело, записане за git ref:, фіксується в блокуванні за комітом, на який вказало це посилання, тоді як збірка шукає закріплення джерела за версією, яку називає сутність, тож цей рядок ніколи не порівнюється — ні збіркою, ні перевірним отриманням. Lockfile однаково закріплює коміт, і кожна збірка перевіряє кешований архів щодо нього.
Запис довіри до плагінів
Деякі плагіни, які підключає робочий простір, ніколи не впливають на згенерований результат. Підключення plugins.governance у ролі ir-verdict або render-verdict, а також кожне підключення plugins.linter повертають вердикт «прийняти або відхилити» і нічого більше — жоден їхній байт не потрапляє в артефакт. Тож вони не входять до того, що збірка відтворює байт у байт, і lock-файл, який фіксує саме це, — невідповідне місце для них.
Натомість їхні ідентичності записуються в другий файл, що комітиться: plugins-trust.yaml, поруч із lock-файлом. Він містить по одному запису на кожен такий плагін, де зазначено координату ідентичності плагіна, вибрану для нього версію та дайджест вмісту розв’язаного артефакту — а також підпис, який pull перевірив для цього артефакту, якщо перевірив, і, якщо видавець відтоді, як опублікував артефакт, позначив його застарілим, — маркер, який pull знайшов і перевірив. Схема запису довіри до плагінів описує файл поле за полем.
Комітьте plugins-trust.yaml разом із lock-файлом з тієї ж причини, з якої комітите lock-файл: запис, що зберігається поза системою контролю версій, ніхто не може переглянути й ні з чим не можна порівняти. Закомічений, він є єдиним спільним твердженням про те, до якого плагіна розв’язалося кожне з цих підключень, а diff над ним називає ідентичність, що змінилася.
Файл з’являється лише тоді, коли є що записати. Робочий простір, що не підключає жодного плагіна, який повертає вердикт, не розв’язує жодної такої ідентичності, тож pull не записує файл і нічого про нього не повідомляє — це відсутність, а не відсутній файл. Коли pull усе ж створює його, він називає створений файл і радить вам закомітити його. Наступний pull додає ідентичність, якої запис ще не містить, і залишає кожну вже записану ідентичність точно такою, як вона є.
Про кожну зміну цього файлу повідомляється, і ні про що інше. Pull, що змінює запис, виводить по одному рядку на кожен змінений запис, називаючи плагін і тип зміни: ідентичність, записана вперше; ідентичність, прийнята замість наявної (з назвою обох, щоб ви бачили, що замінено); застарілість, записана для артефакту, який запис уже називає; застарілість, знята з нього; підпис, записаний для нього або знятий із нього; або видалення запису. Описаний вище рядок про створення окремий і стосується файлу, а не запису, тож перше розв’язання повідомляє обидва: цей файл новий і його слід закомітити, а це ідентичності, які він тепер містить.
Pull, що залишає запис точно таким, яким він був, нічого про нього не повідомляє. Тож рядок про цей файл означає, що закомічений файл змінився і його diff варто прочитати — а тут це важливіше, ніж для lock-файлу. Усе, що фіксує lock-файл, також входить до того, що збірка відтворює байт у байт, тож зміна там має друге місце, де вона проявиться; ідентичність плагіна-вердикту такого місця не має. Цей файл — єдине місце, де записано заміну шлюзу.
aggrega pull --dry-run нічого з цього не повідомляє, бо нічого не змінює. Натомість він наводить запис серед файлів, які записав би, як описано в розділі Попередній перегляд того, що записав би pull.
Застарілість додається до запису, який уже є, і це не те саме, що його переписування. Якщо видавець позначає застарілим плагін, якому ви вже довіряєте, наступний aggrega pull записує маркер у наявний запис цього плагіна — координата, версія та дайджест не змінюються, бо артефакт не змінився і нічого нового не приймається. Тож звичайний pull може додати блок deprecation, і лише явне оновлення будь-коли змінює ідентичність. Маркер записується лише для артефакту, який запис уже називає, і жоден pull не відстежує маркер, який перестали публікувати: записаний маркер зникає лише разом із записом, що його містив, тобто або коли цей запис видаляється, або коли явне оновлення повторно розв’язує плагін і не знаходить маркера на байтах, які запис уже фіксує.
Перевірений підпис записується в запис так само, і кожен pull визначає його заново. Pull під час кожного запуску перевіряє підпис кожного з цих плагінів за політикою довіри його реєстру — плагін, який надає реєстр, щоразу завантажується за версією, оскільки його ніщо не фіксує, — і записує перевірене в запис плагіна, знову не торкаючись ідентичності: режим, підписувача, який збігся, і дайджест закешованого пакета підпису — той самий signature, що міститься в записі lock-файлу. На відміну від маркера, ця відповідь замінює те, що містив запис, а якщо 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, без суфікса версії. Це повторно розв’язує цей один плагін і переписує його запис, не торкаючись жодної іншої зафіксованої залежності та жодної іншої записаної ідентичності, — і це працює, хоча плагін не має фіксації в lock-файлі, бо названа ціль може також називати одне з цих підключень. Простий 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, і нічого, що розв’язується іншим способом. Саме так зазвичай розв’язується підключення з вердиктом — у lockfile його ніщо не закріплює, тож його байти надходять із кешу, і саме під час цього читання розв’язаний дайджест порівнюється із записаним. Плагін з вердиктом, який робочий простір розв’язує іншим способом, ніколи не доходить до цього читання, і його регулює те, що регулює спосіб, яким його розв’язано, а не запис: байти з копії всередині бінарного файлу компілятора ідентифікуються версією компілятора, яка їх містить, .wasm поруч із сутністю каталогу — це файл у вашому власному каталозі, явний шлях файлової системи — це шлях, який ви вказали, а плагін із закріпленням у lockfile регулюється цим закріпленням. Друга половина звіряння конфігурації із записом так не обмежена: кожен запис, який містить запис довіри, має й далі відповідати налаштованому підключенню, хоч би як цей плагін розв’язувався. Отже, запис встановлює, що названі в ньому шлюзи досі підключені, хоч би що їх постачало, і встановлює ідентичність артефакту тих, що постачаються з кешу.
Дотримання проти оновлення
За замовчуванням 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 (за замовчуванням реалізується lock; оновлення вмикається явно), і саме це робить автоматичний 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 за будь-якого значення цього прапорця: перевірка не записує закріплення, якого бракує в entity.lock, і не зупиняється через нього, тож прапорець нічого б не змінив.
Вона дотримується записаних закріплень точно так само, як pull. Залежність, яку закріплює lock-файл, розвʼязується до закріпленої версії та перевіряється за закріпленим дайджестом, а сутність, яку надає локальний каталог, розвʼязується з цього каталогу, як описано в розділі Дотримання та оновлення. Отже:
- Посилання, реєстр якого після pull опублікував новішу версію, не є розбіжністю. Pull зберіг би його закріплення, тож lock-файл досі той, який записав би pull; новішу версію приймають за допомогою
aggrega pull --upgrade. - Реєстр, який тепер віддає інші байти під закріпленою версією, зупиняє перевірку тією самою помилкою цілісності, що зупиняє pull, а не повідомляє про зміну як про розбіжність.
- Про відредагований вручну рядок lock-файлу, відредаговану сутність Release і відредаговану в локальному каталозі сутність повідомляється окремо, бо кожне з них — відмінність між lock-файлом і тим, що pull розвʼязує зараз.
Вона читає та заповнює кеш так само, як pull. Запис, який кеш зберігає під його закріпленням, — сутність каталогу або .wasm плагіна — читається звідти без звернення до реєстру; саме це дає змогу запускати перевірку в офлайн-режимі над робочим простором, який заповнив pull з доступом до мережі. Запис, якого кеш не містить, завантажується так само, як його завантажує pull, а запис, що більше не відповідає своєму закріпленню, обробляється точно так, як його обробляє pull. Отже, перевірка може доповнити кеш, але ніколи не зсуває закріплення.
Вона порівнює записані підписи в обох файлах
Підпис, який pull перевірив для артефакту, є частиною того, що він записує: signature у записі lock-файлу та в записі plugins-trust.yaml для плагіна, підключеного в ролі вердикту. Коли закріплення збігаються, перевірка звіряє кожен записаний підпис із тим, який pull записав би зараз, і повідомляє про кожен, який pull записав би там, де жодного не записано, замінив би або очистив, під помилкою A recorded signature is not the one a pull would record (Записаний підпис не той, який записав би pull). Кожен такий запис в обох файлах називається за один запуск.
Які записи lock-файлу вона перевіряє, визначає сам pull. Повторний pull запитує реєстр про підпис запису саме там, де це описано в розділі Дотримання та оновлення, і перевірка використовує той самий вибір:
- Про два випадки повідомляється без звернення до реєстру, бо pull переписує їх незалежно від відповіді реєстру: запис, який надає кеш і який не містить підпису там, де конфігурація довіри його вимагає, — pull записує підпис артефакту або зупиняється, якщо його неможливо встановити, — і запис, записаний підпис якого зроблено для іншого артефакту, який pull замінює власним підписом артефакту.
- Про кожен інший запис, який pull перевірив би знову, запитується реєстр, бо лише відповідь реєстру показує, чи змінив би його pull: запис, байти якого завантажила ця перевірка, і запис, кешований пакет підпису якого видалено, неможливо прочитати або змінено. Перевірка запитує реєстр, як зробив би pull, і повідомляє про запис, якщо відповідь записує, замінює або очищує його підпис. Перевірений пакет підпису кешується так само, як його кешує pull, тож запис, кешований пакет якого видалено, тоді як реєстр досі віддає записаний підпис, проходить перевірку й залишає кеш відновленим.
Про запис, записаний підпис якого приймає збірка, і про запис без підпису, для якого ніщо не вимагає підпису, реєстр не запитують ні pull, ні перевірка.
Запис довіри до плагінів звіряється з тим самим pull. Кожен pull перевіряє в реєстрі підпис кожного плагіна, підключеного в ролі вердикту, і так само робить перевірка, яка повідомляє про запис, чий підпис ця верифікація записала б, замінила б або очистила б. Про плагін, для якого запис не містить елемента, повідомляється там, де збірка відхиляє його через відсутність записаного підпису, бо pull записує елемент із його підписом, а доти збірка відхиляє плагін. Будь-який інший — це перша поява, про яку перевірка не повідомляє, так само як не повідомляє про жодну ідентичність, якої запис ще не містить. В офлайн-режимі перевірка не запитує реєстр про ці плагіни, а що вона повідомляє натомість, описано в розділі Офлайн.
Позначки застарілості не порівнюються. Позначка, додана до артефакту після pull, — це стан реєстру, і вона змінюється без жодних змін у робочому просторі; перевірка, що завершувалася б невдачею через неї, провалювала б перевірку файлів, яких ви не торкалися. З тієї ж причини записана позначка лише попереджає збірку, а не зупиняє її. Тож pull може записати позначку для запису, який перевірка пропустила.
Попередній перегляд того, що записав би 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 не записується і не створюється, жоден entity lock не записується і не видаляється, і жоден запис довіри не створюється і не змінюється. Якщо можливість надає більше ніж один плагін-провайдер і ніщо не зробило вибору між ними, виконання зупиняється й називає, що потрібно вказати, замість того щоб запропонувати записати вибір у вашу конфігурацію — попередній перегляд не редагує конфігураційний файл мимохідь.
Саме розв’язання все одно виконується, тож кеш усе одно заповнюється. Які зовнішні вхідні дані споживає сутність Release, визначається її рендерингом, а виконання, яке відмовилося б від розв’язання, не мало б про що звітувати, тому --dry-run завантажує і зберігає дані точно так само, як pull. Вміст у .aggrega/cache читається лише через закріплення, записані в lockfile, тож його заповнення не змінює нічого з того, що розв’язує збірка; dry run показує саме те, що записав би pull.
Голий --upgrade із цим прапорцем нічого не запитує. Підтвердження існує тому, що повне оновлення відкидає всі записані закріплення, а попередній перегляд не відкидає жодного — тож aggrega pull --dry-run --upgrade --release <release> — саме та форма, до якої варто вдатися, коли ви хочете дізнатися, чого вам коштувало б оновлення, і вона виконується без відповіді.
Прапорець не приймається разом із --verify, який і так не записує жодного з цих файлів. Така пара залишила б прапорець бездіяльним, хоча виглядало б, ніби він щось зробив, тому її відхиляють, а не ігнорують.
Одне попередній перегляд із закріпленням не завжди може показати повністю, і він повідомляє про це, коли так стається. Pull, якому наказано закріплювати, переписує entity.lock поруч із кожною сутністю Recipe і FeatureRecipe, а потім рендерить сутність Release, щоб виявити її зовнішні вхідні дані; попередній перегляд не чіпає цих lock-файлів, тож якщо записане там закріплення застаріло — наприклад, ви відредагували імпортований файл після закріплення, — цей рендеринг звіряється із застарілим дайджестом, який досі містить незаписаний lock, і зупиняється. Усе інше у звіті — саме те, що записав би pull; неповними є лише закріплення зовнішніх вхідних даних у показаному lockfile. Виконання повідомляє про це і у своєму виводі, і в діагностиці, а не видає вам lockfile, який виглядає повним. Перше розв’язання робочого простору це не зачіпає, бо ще немає записаного дайджесту, щодо якого щось могло б застаріти.
Композиція, яку описують ці фіксації
Lock-файл фіксує те, що споживатиме збирання цієї Release, тому розв’язання будує ту саму композицію, що й збирання: воно розв’язує документи, застосовує перетворення, які оголошують прикріплення робочого простору, і пропускає результат через перевірки, які збирання виконує над завершеним графом. Із цього випливають дві речі, і обидві проявляються під час проходу, що записує lock-файл, а не під час першого збирання, яке його читає.
Композиція, яку ці перевірки відхиляють, зупиняє pull. Ребро uses:, ціль якого не задовольняє selector: свого сокета, сутність Feature, прикріплена до компонента, якого не допускає її appliesTo:, і будь-яке інше порушення, про яке повідомляють ці перевірки, зупиняють цю команду з тією самою діагностикою, яку виводить збирання тих самих документів, — і зупинка називає всі знахідки за один запуск, а не лише першу, тож один прохід дає вам увесь список для виправлення. Це відбувається до запису, тому <release-stem>.lock і plugins-trust.yaml лишаються такими, якими були, і Release, яка не збереться, ніколи не записується як така, що розв’язалася чисто. Чого це не охоплює, так це прикріплень, що повертають вердикт: жодне прикріплення ir-verdict чи render-verdict тут не запускається, тож відхильний вердикт зупиняє збирання, lint рівня релізу чи валідацію рівня релізу, яка його викликає, а не цю команду.
Прикріплення в ролі, що формує граф, запускається під час цього проходу, тож плагін, який не розв’язується, зупиняє pull. Прикріплення label-transform визначає мітки вузлів до того, як із ними щось зіставляється, а прикріплення annotation-transform додає анотації, які розгортаються в прикріплення Feature, — обидва змінюють вміст графа, тож побудова графа означає їх виклик, а виклик означає наявність власних байтів кожного плагіна. Плагін, байти якого цей прохід не може отримати, зупиняє запуск із назвою плагіна та того, що для нього не вдалося знайти, — це та сама відмова, яку дає збирання того самого робочого простору, коли не може їх отримати. Викликається список прикріплень, щойно розв’язаний цим проходом, разом із налаштуваннями та файлами визначень, які lock-файл записує, щоб пізніше збирання могло їх відтворити, тож обидва проходи запускають те саме прикріплення з тими самими вхідними даними.
Сутність 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.
Ця зупинка й неповний запуск — свідомо різні результати. Рендеринг, який не може завершитися, — той, що описують Як розв’язання знаходить зовнішні вхідні дані і Офлайн, — лишає всі фіксації залежностей правильними, тож фіксації записуються, а нестача повідомляється. Композиція, яку відхиляють перевірки, не є нестачею в розв’язаному: це 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 офлайн-відмовою із зазначенням залежності: запис підпису означає звернення до її реєстру, як описано в Honoring vs. updating (Дотримання чи оновлення). Дозвіл мережі для цього одного запуску записує його. Записаний підпис, який збірка приймає, повторно не перевіряється, тож він не зупиняє офлайн-pull.
Зовнішній вхід — єдиний, що не зупиняє, і натомість про це повідомляє. Рендер, який їх знаходить, не може завантажити те, що ще не збережено, тож офлайн-pull над сутністю Release із незафіксованим зовнішнім входом завершується, записує кожну розв’язану фіксацію залежностей і повідомляє три речі: що рендер не завершився, що саме він зафіксував і що збірка цієї сутності Release зупиниться із зазначенням URL. Записані фіксації залежностей правильні — ніщо в них не залежало від рендеру, — тож їх зберігають, а не викидають, щоб читачеві не довелося їх відтворювати.
Це навмисно, а не прогалина, і перемикача для цього немає. Pull, що відкинув би правильну роботу, коштував би вам успішної частини; pull, що мовчав би, дав би вам lock-файл, який виглядає повним, але таким не є. Повідомлення про це — єдиний результат, що дає вам змогу діяти: запустіть pull знову із середовища з підключенням або з такого, чий кеш уже містить вміст, і та сама команда це зафіксує.
Отже, офлайн-pull — це відмова звертатися до мережі, а не зменшений результат для всього, що називає документ, а для зовнішніх входів — завершене розв’язання, яке повідомляє, чого воно не змогло досягти. Наявний lock-файл — це той, чиє розв’язання залежностей завершилося; чи повні його зовнішні входи, повідомляє власний вивід pull, і саме цього потім вимагає збірка.
--verify в офлайн-режимі охоплює менше й повідомляє про це. Щоб дізнатися, куди записане посилання на джерело вказує сьогодні, потрібно звернутися до його віддаленого репозиторію, а офлайн-режим це забороняє. Тож офлайн---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 переписав би незалежно від відповіді реєстру, і далі повідомляється офлайн, бо для цього відповідь не потрібна, як описано в It compares the recorded signatures, in both files (Він порівнює записані підписи в обох файлах).
Плагін, підключений у ролі вердикту й наданий реєстром, — це місце, де офлайн-verify і офлайн-pull розходяться. Такий плагін ніколи не фіксується в lock-файлі, тож кожен pull розв’язує його .wasm з реєстру, і офлайн-pull над робочим простором, що його підключає, зупиняється тут, називаючи плагін як такий, чий .wasm не вдалося розв’язати, — навіть якщо кеш вмісту його містить і незалежно від того, чи позначено реєстр як advisory або чи пропускає він перевірку підписів. Офлайн-verify натомість нічого не питає в реєстру про плагін: він читає плагін із кешу вмісту, як це робить збірка, і зупиняється, якщо кеш не містить його .wasm або містить такий, що вже не відповідає дайджесту з опублікованого маніфесту. Він і далі звіряє ідентичність плагіна із записом довіри до плагінів і повторно перевіряє його функції хоста щодо цього .wasm, зупиняючись за будь-якої розбіжності, точно як verify з підключенням. Він повідомляє про плагін, коли pull переписує його запис незалежно від відповіді реєстру, тобто коли збірка відхиляє плагін через його запис: через відсутність записаного підпису — бо запис не містить підпису або запис довіри не має запису для нього, — або тому, що підпис у записі зроблено для іншого артефакту, і pull замінює його власним підписом плагіна. Кожен інший запис — той, чий підпис збірка приймає, і той, чий кешований пакет підпису видалено або змінено, — він називає в рядку про те, що підпис не перевірено, і нічого не повідомляє про цей підпис:
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 в ізольованому середовищі залишається доступним; він не повідомляє вам лише, чи посилання відтоді змістилося і чи пропущений підпис було б записано знову. Перевірка, що читає лише код виходу, охоплює це тільки тоді, коли verify виконується з підключенням.
Інтеграція з aggrega build
- Перевірка.
aggrega buildперевіряє кожну розв’язану залежність за lockfile і зупиняється в разі розбіжності: сутність, бібліотека чи плагін, чий вміст більше не відповідає закріпленню; посилання, до якого Release тепер доходить, але яке lockfile не закріплює, або закріплене посилання, до якого Release більше не доходить; а також файл Release, відредагований після pull. Щоб усунути це, виконайтеaggrega pull --release <release>— команду, яку виводить зупинка: pull розв’язує Release у його поточному стані, переписує закріплення, що змінилися, і зберігає всі інші, тож нічого не зміщується без ваших змін. Якщо змінився файл у локальному джерелі сутності Recipe, pull спершу називаєaggrega pinдля цієї сутності, як описано в розділі Блокування сутності. Lockfile, щойно записаний цією командою, проходить цю перевірку, бо команда виконує ту саму перевірку перед записом; збірка, що зупиняється через розбіжність одразу після pull, отримала інші вхідні дані, ніж pull, — каталог--catalog, переданий одній команді й не переданий іншій, або конфігурацію робочого простору, відредаговану між ними, — тож запускайте обидві над тими самими даними.aggrega validate --releaseі кожен вибірaggrega inspect, що розв’язує Release, застосовують до lockfile ту саму перевірку й відмовляють із тією самою зупинкою, тож жоден із них не пропускає lockfile, який відхиляє збірка. - Автоматичний pull. Якщо lockfile відсутній і
auto_pullмає значення true,aggrega buildспершу автоматично виконує pull. Якщоauto_pullмає значення false (типове), збірка зупиняється й пропонує виконати pull. Pull, який запускає збірка, дотримуєтьсяpin_sources_at_pull, тож над незакріпленою сутністю він зупиняється так само, як звичайний pull. Крок pull, який виконує збірка, — той самий, що описано на цій сторінці, тож збірка, яка заповнює наявний lockfile, зупиняється через зміщене посилання на джерело так само, якaggrega pull, — див. Детермінованість і цілісність. - Офлайн. В офлайн-режимі
aggrega buildвикористовує лише те, що вже є на машині, і відмовляє в доступі до мережі до будь-якої спроби з’єднання. Посилання, вмісту якого немає в кеші, зупиняє збірку, а не спричиняє збій посеред завантаження, а збірка без lockfile, якій не доручено його заповнити, зупиняється, називаючи pull, що заповнив би його, — так само, як онлайн.--auto-pullне відхиляється: заповнення, яке він запитує, — це pull, описаний на цій сторінці, тож над сутностями каталогу, що вже є в кеші або в локальному каталозі, він записує lockfile, не звертаючись до реєстру, — сутність Recipe, чий chart завантажується з віддаленого джерела, розв’язується знову, тож офлайн вона зупиняється, навіть якщо кеш містить цей chart, — а посилання, якого немає ніде, — або кешоване, чийого обов’язкового підпису lockfile не записує чи чий записаний підпис збірка не приймає, — зупиняє його власною відмовою pull із назвою цього посилання.--upgradeвідхиляється з причини, наведеної в розділі Офлайн. - Пошук у каталозі. Pull враховує
catalog_dirsз.aggrega-config.yaml, навіть якщо--catalogне задано, — а також власні каталоги сутності Release, якщо конфігурація задає їх уworkspace.releases, — і розв’язує той самий стек пошуку за принципом «перший виграє», що йaggrega build, тож залежності, які він закріплює, відповідають тому, що шукає build. Указаний каталог, який не є каталогом, — наприклад, там нічого не існує, — відхиляється обома командами до того, як щось буде розв’язано чи записано, із зазначенням запису, а також файлу конфігурації та рядка, що його вказують, як показано в розділі Звідки зчитуються локальні сутності.
Як розв’язання знаходить зовнішні вхідні дані
Ніщо в цьому розділі не змінює наведеного вище правила — досі є лише один момент, коли щось закріплюється, і це ця команда. Тут описано, як команда доходить до третього з трьох видів, що важливо, коли ви вбудовуєте розв’язання в конвеєр, аналізуєте запуск, що спрацював частково, або міркуєте, чому ця команда взагалі виконує рендеринг.
Сутність каталогу й артефакт джерела названо в документі; зовнішні вхідні дані — ні. Розв’язати перші два означає прочитати те, що ви написали. Зовнішні вхідні дані називає провайдер посеред рендерингу, і які URL він назве, залежить від значень, що рендеряться, — відсутній запис у values залишає цілу гілку схеми chart нескомпільованою, а кожне віддалене посилання в цій гілці — незапитаним. Жодне читання Release не може перелічити цю множину.
Тому команда робить дві речі за один прохід: розв’язує й закріплює замикання, яке називають документи, а потім рендерить це замикання, щоб побачити, які віддалені документи запитують провайдери. Відрендерені артефакти відкидаються, а закріплення зберігаються. Обидва кроки внутрішні для однієї команди, і жоден не є другим моментом, коли щось могло б закріпитися, — lockfile записується один раз, і він містить усі закріплення.
Варто знати два наслідки, перш ніж вбудовувати розв’язання в автоматизований конвеєр як дешевий крок. Воно коштує більше, ніж розв’язання, яке лише читає документи, бо виконує рендеринг. І воно може завершитися збоєм з причини, неможливої для розв’язання лише за документами: провайдер не може відрендерити цей Release. У такому разі закріплення залежностей однаково записуються, бо вони ніяк не залежали від рендерингу, а діагностика називає етап, що зупинився, те, що було закріплено, і те, що збірка зупиниться, назвавши незакріплений URL. Запуск не втрачено, а в розділі Офлайн показано той самий результат, досягнутий іншим шляхом.
Рендеринг також перевіряє 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 (Розв’язання координати джерела реєструє вужчий набір функцій). Змінюваний тег або гілку Git закріплюють за конкретним комітом, на який вони вказують, а створене вами посилання записується поруч із ним. Під час збирання дайджест кешованого архіву повторно звіряється з lockfile, тож підроблений кеш буде виявлено.
Записаний ref утримується на коміті, який він закріпив. Ref записується тому, що наступні запуски знову його запитують, а не для зручності читання: збирання запитує, який артефакт він називає, а pull — чи вказує він досі туди ж, куди й раніше. pull, який не є оновленням, повторно запитує кожен записаний ref, куди той вказує, і ref, що змістився у своєму віддаленому репозиторії, зупиняє запуск — із зазначенням артефакту, ref, коміту, закріпленого в lockfile, і коміту, на який він розв’язується тепер, — замість того щоб прийняти зміщення. Щоб прийняти його, виконайте aggrega pull --upgrade --release <release>. Цільове оновлення, яке називає URI сутностей, цього не робить: посилання на джерело не є сутністю, яку можна назвати, тому цільовий запуск утримує його так само, як і звичайний pull.
Ця перевірка — єдине, чого повторна перевірка дайджесту під час збирання не може зробити за вас. Pull, який прийняв би зміщений ref, переписав би отримані байти й записаний дайджест одночасно, тож два значення, які порівнює збирання, змістилися б разом і збіглися б, — і ви збирали б інший вміст джерела, ніж той, за яким перевіряли lockfile, і ніщо б про це не повідомило.
Так утримується лише ref, який записано в lockfile, а ref записується щоразу, коли ви його пишете. Сутність Recipe, що називає своє джерело лише через version:, не має ref, тож наступному запуску нічого перепитувати, — і це правильно, бо версія, яку ви написали самі, не може зміститися без вашого відома. У довіднику з lockfile описано, що саме записується.
Пишіть ref, а не коміт. build знаходить артефакт із джерела git за написаним вами ref, зіставляючи його з ref, записаним у lockfile, тож ref: v1.2.3 збирається з коміту, за яким цей тег було закріплено, і коміт ніколи не мусить з’являтися у вашій сутності Recipe. Вказати натомість змінний тег у version: не вийде, і так і задумано: version: зіставляється в написаному вигляді, а для джерела git lockfile закріплює коміт.
Lockfile закріплює вміст, отриманий із реєстрів і віддалених джерел, і записує дайджест кожної сутності, яку він розв’язує з ваших каталогів, — за файлом сутності й кожним файлом, який вона називає поруч, як описано в розділі Lockfile, — а також кожного файлу Release, який прочитало розв’язання. Файли джерела, що починається з ./ або ../, і файл артефакту, який імпортує сутність, також закріплюються поодинці в lock поруч із цією сутністю, як описано в розділі 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 — перевіряє lockfile і автоматично виконує pull, якщо це налаштовано.
- ./aggrega-serve.md — демон надає це саме розв’язання через
aggrega/resolveDependencies, а також усерединіaggrega/buildдля запиту, полеautoPullякого цього вимагає, тож редактор може запустити його, не залишаючи сеансу; в обох випадках воно виконується лише тоді, коли запит його називає, і записує той самий lockfile, що й ця команда. - ./aggrega-push.md — публікує сутності каталогу до реєстру.
- ./aggrega-lint.md — перевірка перед публікацією, що передує
aggrega push. - ../../architecture/13-catalog-and-registry.md — повний опис моделі каталогу, lockfile і кешу.
Синтаксис
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; у lockfile не записується |
--dry-run | false | Розв’язує залежності й виводить те, що записав би цей pull, замість запису: шлях кожного файлу та вміст, який він містив би, надходять у stdout, а lockfile, entity.lock поруч із кожною сутністю Recipe та FeatureRecipe, записані pin яких змінилися б за —pin-sources, і запис довіри до плагінів залишаються незмінними. Називаються лише ті файли, які справді змінилися б. Саме розв’язання виконується так само, як і без прапорця, тож кеш вмісту все одно заповнюється, pull, що зупинився б на незакріпленій сутності, зупиняється й тут, а голий —upgrade нічого не запитує, бо не відкидає жодного pin — dry run показує саме те, що записав би pull. Не приймається разом із —verify, який і так не записує жодного з них |
--include-prerelease | false | Ще не реалізовано: приймається й ігнорується, тож скрипт, який його передає, працюватиме й тоді, коли прапорець почне діяти |
--pin-sources | false | Виконує крок закріплення автора сутності для сутностей Recipes і FeatureRecipes, які збирає ця Release, записуючи в entity.lock поруч із кожною pin для кожного вхідного елемента, який вона читає — віддаленого source:, записаного повністю, файлу, який імпортує запис artifacts, і кожного файлу локального source, — замість зупинки на сутності, lock якої їх не записує. Це той самий крок, що й aggrega pin, і він записує ті самі байти. Він записує поруч із сутністю, тому виконується лише там, де сутність має доступне для запису місце: документ в одному з ваших каталогів. Сутність, розв’язана з кешу, такого місця не має і ніколи не закріплюється. Перевизначає pin_sources_at_pull робочого простору в обох напрямках: —pin-sources закріплює для цього запуску, а —pin-sources=false зупиняє для цього запуску, незалежно від налаштування |
--progress | false | Примусово вмикає відображення прогресу pull, навіть коли stderr не є терміналом, виводячи один простий рядок на кожен крок після його завершення разом із часом. За замовчуванням — auto: інтерактивний список фаз показується лише тоді, коли stderr є терміналом, що інтерпретує escape-послідовності, термінал, який їх не інтерпретує, отримує ті самі прості рядки, а перенаправлений чи переданий через конвеєр вивід не отримує нічого |
--quiet | false | Вимикає відображення прогресу pull у stderr. Не впливає на stdout. Має пріоритет над —progress |
--release | — | Шлях до YAML-файлу Release (обов’язково). Відносний шлях розв’язується відносно каталогу, у якому ви запускаєте команду, а не відносно кореня робочого простору. Якщо цей каталог не належить до жодного робочого простору і корінь не вказано, абсолютний шлях знаходить робочий простір із власної теки Release |
--upgrade | false | Повторно розв’язує залежності за поточним станом реєстру, підіймаючи кожну до найвищої доступної версії. Без аргументів (без позиційних URI) відкидає lockfile і повторно розв’язує кожну сутність, попередньо запитуючи підтвердження, бо відкидає кожен записаний pin; з одним чи кількома URI сутностей повторно розв’язує лише їх, зберігаючи незмінними всі інші pin і записані зовнішні вхідні дані, і нічого не запитує (несумісний із —verify) |
--verify | false | Перевіряє наявний lockfile відносно розв’язання залежностей, яке pull виконав би зараз, не записуючи lockfile, запис довіри до плагінів чи будь-який entity.lock; завершується з ненульовим кодом у разі розбіжності або відсутності lockfile. Розв’язання дотримується pin, записаних у lockfile, точно так само, як pull: посилання, реєстр якого після pull опублікував новішу версію, не є розбіжністю, бо pull зберіг би його pin, а реєстр, що тепер надає інші байти під закріпленою версією, зупиняє перевірку так само, як зупиняє pull. Кеш вмісту читається й заповнюється так само, як pull його читає й заповнює: запис, який кеш містить під його pin, читається звідти без звернення до реєстру, запис, якого кеш не містить, отримується, а запис, що більше не відповідає своєму pin, обробляється точно так само, як його обробляє pull. Також звіряє entity.lock поруч із кожною сутністю Recipe та FeatureRecipe у ваших каталогах, до якої доходить Release, з тим, із чим його порівнює збірка, і завершується з ненульовим кодом на pin, який збірка відхилила б: імпортований файл, що більше не відповідає записаному дайджесту, локальне джерело, файли якого більше не відповідають записаним дайджестам, або pin джерела, що не узгоджується з lockfile. Також порівнює підпис, який lockfile записує для кожного артефакту, і запис довіри до плагінів для кожного плагіна з тим, який pull записав би зараз, і завершується з ненульовим кодом там, де pull записав би, замінив або очистив його: підпис, якого вимагає вимога, але який не записано, і підпис, зроблений для іншого артефакту, повідомляються без звернення до реєстру, бо pull перезаписує їх незалежно від відповіді; підпис, який pull шукає знову і міг би записати без змін — артефакт було отримано або його кешований пакет підпису видалено чи змінено, — перевіряється в його реєстрі, а в офлайн-режимі залишається неперевіреним із рядком, що про це повідомляє; і кожен плагін, який охоплює запис довіри до плагінів, перевіряється в його реєстрі, як його перевіряє кожен pull, окрім офлайн-режиму, де він читається з кешу вмісту так, як його читає збірка, його ідентичність і функції хоста все одно перевіряються, а підпис залишається неперевіреним із рядком, що про це повідомляє, хіба що збірка відхиляє його через відсутність запису або запис, зроблений для іншого артефакту, — про це повідомляється. Позначки застарілості не порівнюються. Також повідомляє версії компілятора та основних плагінів, записані в lockfile, — лише для аудиту, без порівняння з цим двійковим файлом, тож різниця в інструментарії ніколи не є розбіжністю. Не приймається разом із —pin-sources, з будь-яким значенням: перевірка не записує pin, якого бракує в entity.lock, і не зупиняється на ньому, тож прапорець нічого б не змінив (несумісний із —upgrade) |
--yes | false | Заздалегідь відповідає на запит підтвердження голого —upgrade для неінтерактивного використання. Він стосується лише цього одного запиту: жодна інша форма pull нічого не запитує, тож його передавання там нічого не змінює |