Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Схема Aggrega Entity Lock

Згенерований довідник. Не редагуйте вручну — згенеруйте повторно з опублікованої JSON Schema.

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

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

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

Властивості

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

Додаткові властивості не дозволені.

entity-lock.sourceDigests[]

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

Додаткові властивості не дозволені.

entity-lock.artifactDigests[]

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

Додаткові властивості не дозволені.

entity-lock.localSourceDigests[]

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

Додаткові властивості не дозволені.

entity-lock.ignore

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

ВластивістьТипОбов’язковаОпис
pluginobjectніПлагін, який обслуговував можливість сутності в робочому просторі автора на момент закріплення сутності, — прив’язка провайдера робочого простору для цієї можливості або, інакше, плагін, вбудований у двійковий файл aggrega, — названий без версії, і правила ігнорування, які він оголосив. Ні версія, ні дайджест плагіна не записуються: кожне читання застосовує саме правила, тож повторне закріплення під іншим випуском того самого плагіна лишає lock незмінним, якщо правила не змінилися. Якщо власний плагін для цієї можливості під час pull оголошує інші правила, pull повідомляє про це в попередженні, називаючи обидва плагіни й різницю, і ніколи не зупиняється через це. Відсутній, якщо жоден плагін не обслуговував цю можливість.
rulesobject[]ніТочні складені правила в порядку їх застосування: шаблони плагіна, потім рядки кожного файлу ігнорування, який називає плагін і який знайшов обхід (власний файл каталогу — перед файлами під ним), потім рядки авторського .aggregaignore поруч із сутністю. Пізніший збіг перекриває раніший, тож авторський файл має останнє слово щодо будь-якого шляху, який він називає, а рядок, що починається з !, повертає те, що виключило раніше правило. У каталог, який виключає правило, обхід не заходить, тож файл під ним повертається лише тоді, коли повертається сам каталог.

Додаткові властивості не дозволені.

entity-lock.ignore.plugin

Плагін, який обслуговував можливість сутності в робочому просторі автора на момент закріплення сутності, — прив’язка провайдера робочого простору для цієї можливості або, інакше, плагін, вбудований у двійковий файл aggrega, — названий без версії, і правила ігнорування, які він оголосив. Ні версія, ні дайджест плагіна не записуються: кожне читання застосовує саме правила, тож повторне закріплення під іншим випуском того самого плагіна лишає lock незмінним, якщо правила не змінилися. Якщо власний плагін для цієї можливості під час pull оголошує інші правила, pull повідомляє про це в попередженні, називаючи обидва плагіни й різницю, і ніколи не зупиняється через це. Відсутній, якщо жоден плагін не обслуговував цю можливість.

ВластивістьТипОбов’язковаОпис
namestringтакПлагін, який обслуговував можливість сутності на момент її закріплення, у вигляді <pluginType>/<name>, без версії: читання застосовує наведені нижче правила, а назва каже, чиї вони. Щонайменше 1 символ.
patternsstring[]ніШаблони ігнорування, які оголосив плагін, у тому вигляді, у якому він їх оголосив.
filesstring[]ніНазви файлів ігнорування, які, за оголошенням плагіна, його екосистема враховує всередині джерела.

Додаткові властивості не дозволені.

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

Додаткові властивості не дозволені.