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

Plugin

Plugin — це плагін WebAssembly з адресацією за вмістом: артефакт .wasm, розміщений в OCI і закріплений дайджестом sha256, який оголошує тип сокета, що він реалізує, версію ABI, на яку він орієнтований, необов’язковий вказівник на підпис і необов’язковий блок runtime. Ця сутність є поверхнею авторингу й метаданих для плагіна; розв’язання залежностей закріплює артефакт за дайджестом, а політика довіри конкретного реєстру перевіряє його підпис під час завантаження. Компілятор не інтерпретує поведінку плагіна — він маршрутизує закріплене посилання; середовище виконання WebAssembly виконує байти.

На цій сторінці поле за полем описано поверхню авторингу каталогу Plugin. Про повний робочий процес автора — що таке плагін, самозвіт describe(), життєвий цикл публікація→завантаження→збирання, підписування та версіонування — див. посібник розробника плагінів Wasm. Про точки сокетів, до яких під’єднується плагін, та форми їхніх вхідних і вихідних даних див. контракт плагінів Wasm.

Роль сутності Plugin

Сутність Plugin пов’язує логічну ідентичність плагіна з конкретним артефактом .wasm, а також із метаданими можливостей і середовища виконання, потрібними хосту, щоб безпечно завантажити та запустити його. Крок конвеєра або сокет плагіна посилається на сутність за її URI; сутність містить оголошені можливості, обмеження середовища виконання та вказівник на підпис, а розв’язаний дайджест вмісту зберігається в lock-файлі релізу. Розташування .wasm виводиться з ідентичності плагіна — адресованої координати plugin/<pluginType>/<name>, яка сама складається з metadata.pluginType і простого metadata.name, плюс налаштованого реєстру — і не є полем, яке задає автор. Опосередкування через сутність обов’язкове — пряме посилання на .wasm або на артефакт відхиляється під час завантаження, бо йому не відповідає жодна сутність.

Оголошення сутності Plugin згруповано за типом сокета, і саме з цього групування починається читання сутності:

  • Один блок на тип сокета — spec.provider, spec.pipelineStep, spec.parser, spec.importer. Плагін містить той один блок, який називає його metadata.pluginType, і кожен блок містить список capabilities: — записаний командою aggrega plugin gen-catalog із власного describe() плагіна, — значення якого належить лише цьому блоку: список провайдера називає можливості, які він обслуговує, список кроку конвеєра — можливості провайдера, з якими сумісний його крок, а списки парсера та імпортера називають формати джерел, записані як parse:<format> і import:<format>. Значення несе саме вкладеність — до запису можливості не можна дістатися, не прочитавши спершу блок, який каже, що це за вид твердження.
  • Блок провайдера містить більше, ніж свій список — spec.provider також оголошує, як плагін транслює вид Workload, які платформно-специфічні анотації він читає, і свій контракт поведінки рендерингу (spec.provider.contract: види вхідних даних, збирання меж, роздільники артефактів, повторне використання екземплярів). Вони описують поведінку рендерингу, а не обслуговуваний вимір, тому розміщені поруч зі списком можливостей провайдера, а не всередині нього.
  • Наскрізний сокет не оголошує можливостей — плагін linter, governance або cli не містить жодного з чотирьох блоків, бо не обслуговує ні виміру рендерингу, ні формату джерела.
apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
name: aws-secrets-manager
version: 1.2.0
pluginType: pipeline-step
spec:
abiVersion: v1beta1
pipelineStep:
# capabilities is recorded by `aggrega plugin gen-catalog` from the plugin's describe(); an author may narrow it.
capabilities:
- helm
- compose
signature:
type: sigstore-cosign
runtime:
maxMemoryPages: 256
timeoutMs: 5000
# hostFunctions is recorded by `aggrega plugin sync` from the .wasm — do not author it.
exports:
- name: fetch
operates: emit
scope: own
selector: external-secret resources for the bound credential

metadata

Стандартні метадані каталогу. name, version і pluginType є обов’язковими; version — це строга семантична версія (наприклад, 1.2.0). Необов’язкові поля — description, maintainers, license, repository, home, keywords — мають ту саму форму, що й у кожній сутності каталогу, а metadata не приймає жодного іншого ключа. Опублікована версія незмінна: повторна публікація наявної версії відхиляється на етапі перевірки публікації.

metadata.name є простим — воно не містить префікса сокета. Адресна координата плагіна plugin/<pluginType>/<name> виводиться з metadata.pluginType і простого metadata.name; її не записують в ім’я.

metadata.pluginType

Тип сокета, який реалізує цей плагін. Він розташований в адресному блоці поруч із name і version, оскільки є частиною ідентичності плагіна: він задає сегмент <pluginType> похідної координати plugin/<pluginType>/<name>. Плагін реалізує рівно один тип сокета, взятий із таксономії типів плагінів, яку розпізнає середовище виконання:

  • provider — рендерить вузли IR в артефакти, власні для провайдера.
  • linter — перевіряє авторський вміст і видає діагностичні повідомлення.
  • pipeline-step — крок у pipeline: сутності FeatureRecipe або Recipe, що накладає патчі на набір відрендерених документів.
  • governance — виконує ролі керування в конвеєрі збирання. Під час побудови топології він автоматично додає мітки вузлам графа топології, повертаючи документи JSON Patch, які хост застосовує до проєкції графа, що містить лише мітки. На етапі статичного аналізу або рендерингу він оцінює граф IR або відрендерені артефакти й повертає вердикт «прийняти/відхилити»; правило, що не виконалося, зупиняє збирання. Те, що він може видавати, визначає роль, до якої його приєднано, а не його вид.
  • parser — розбирає сторонній вихідний формат (HCL, TOML, YAML, JSON, …) у структуроване дерево JSON, тож споживач, якому потрібно прочитати формат, що його компілятор не розбирає нативно, працює з розібраним деревом, а не з необробленим текстом.
  • importer — перетворює стороннє джерело опису інфраструктури або агентів на чернетки авторських файлів Aggrega, оголошуючи формати, які він обробляє, як можливості import:<format>.
  • cli — додає підкоманду середовища виконання aggrega <cmd>, яку оператор викликає в командному рядку. Це сокет середовища виконання, відмінний від сокетів рендерингу й конвеєра, що працюють під час компіляції.

Обов’язкове.

spec.abiVersion

Версія ABI хоста й гостя, на яку орієнтується плагін. Допустиме значення — v1beta1; нова ревізія ABI додає ще одне. Обов’язкове.

Оголошення можливостей: один блок на тип сокета

Можливість — це те, що споживач запитує в плагіна: можливість рендерингу, яку запитує Recipe, або вихідний формат, який збірці потрібно прочитати. Можливості плагіна записуються всередині блоку, що належить його типу сокета, тож саме те, у якому блоці розміщено список, визначає значення його записів:

metadata.pluginTypeДе оголошено його можливостіЩо називає запис
providerspec.provider.capabilitiesМожливість рендерингу, яку обслуговує цей плагін, наприклад helm або compose.
pipeline-stepspec.pipelineStep.capabilitiesПровайдер, з відрендереним виводом якого сумісний крок цього плагіна.
parserspec.parser.capabilitiesВихідний формат, який читає цей плагін, записаний як parse:<format>.
importerspec.importer.capabilitiesЗовнішній вихідний формат, з якого цей плагін створює чернетки сутностей, записаний як import:<format>.
linter, governance, cli—Нічого. Ці сокети не обслуговують жодної можливості, тому не містять жодного з чотирьох блоків.

Плагін реалізує рівно один тип сокета, тож його сутність містить один блок. Список — це власний звіт плагіна: aggrega plugin gen-catalog читає describe() плагіна й записує в блок кожну можливість, про яку той повідомляє. Автор може звузити список перед публікацією, вилучивши можливість, про яку повідомляє плагін, але яку опублікована сутність не повинна пропонувати; aggrega validate <entity> --plugin <file.wasm> і aggrega push приймають звужений список і виводять повідомлення, що називає кожну можливість, про яку повідомляє плагін і яку список вилучає. Жодна з них не приймає список, що називає можливість, про яку плагін не повідомляє: обидві відхиляють його, називаючи кожну таку можливість і можливості, про які плагін повідомляє, тож опублікований список ніколи не пропонує більше, ніж надає плагін. Сутність pipeline-step, плагін якої повідомляє про helm і helm-chart, але яка перелічує ще й compose, відхиляється так:

[E0080]
entity "probe-step:1.0.0-rc.1" lists capabilities ["compose"], which the plugin's describe() does not report (it reports ["helm" "helm-chart"]); remove them from the list, which may name only capabilities the plugin reports: wasm: entity contract claim does not match plugin describe()

Споживач розв’язує рівно за тим, що перелічено.

spec.provider

Блок сокета provider для плагіна pluginType: provider: можливості, які він обслуговує, спосіб, у який він перекладає належний платформі вид Workload aggrega.ai/v1beta1, платформно-нативні анотації, які він читає, і його контракт поведінки рендерингу. Блок присутній у кожному плагіні, що рендерить provider, і відсутній у плагінах будь-якого іншого типу. Provider, який рендерить лише вміст із джерела або артефактів без синтезу Workload, однаково містить цей блок — він оголошує там свої можливості та свій контракт і просто пропускає workloadSchema.

spec.provider.capabilities

Можливості, які обслуговує цей provider, — назви можливостей, як-от helm або compose, — форму виводу яких він рендерить. Provider є універсальним щодо артефактів, які мають спільну форму виводу певної можливості, але не щодо всіх можливостей, тому список називає можливості, про які повідомляє сам плагін: aggrega plugin gen-catalog записує його з describe() плагіна, і автор може звузити його перед публікацією. Записи зберігають порядок, у якому їх записано.

Ціль provider, яку запитує сутність Recipe (spec.capability: helm), розв’язується до плагіна provider, список якого містить цю ціль. Коли ту саму ціль перелічує більше ніж один плагін provider, вибір робить робочий простір: вибір plugins.providers у конфігурації робочого простору називає плагін, який слід використати; він розв’язується під час aggrega pull і фіксується в lock-файлі. Якщо вибору немає і кандидат рівно один, використовується цей кандидат; якщо вибору немає, а кандидатів більше одного, збірка зупиняється й називає всіх кандидатів. Неоднозначність вирішується для кожного робочого простору в місці використання, а не правилом унікальності для всього каталогу. Порожній або відсутній список не оголошує жодної можливості, тож плагін не обслуговує жодної цілі.

Назва можливості тут не містить двокрапки. Поле spec.capability сутності Recipe читається як можливість до останньої двокрапки і закріплена версія після неї, тож назву, що містить двокрапку, ніколи не можна було б запитати; плагін, чий describe() повідомляє таку назву, відхиляється під час завантаження, і з нього не генерується жодна сутність для публікації. Те саме стосується можливостей provider, які перелічує плагін pipeline-step. Двокрапка в parse:<format> парсера та import:<format> імпортера є частиною цих назв і залишається.

spec.provider.workloadSchema

Оголошення JSON Schema 2020-12, яке документує, як цей provider перекладає вид Workload aggrega.ai/v1beta1 у нативні маніфести provider. За домовленістю його оголошує provider, який виконує синтез: такий provider оголошує workloadSchema як задокументований контракт перекладу, що описує, які поля Workload споживає provider, які закриті множини приймає кожне поле у формі enum і які обмеження діапазону застосовуються.

Тіло компілюється в JSON Schema 2020-12 під час завантаження сутності Plugin — це структурний запобіжник, який відхиляє некоректну схему під час завантаження, а не під час рендерингу. Чи підтримується Recipe з workload:, визначається здатністю до синтезу прив’язаного provider, а не наявністю цього поля: Recipe в синтезованому режимі, прив’язаний до provider, який не вміє синтезувати, явно зупиняється під час рендерингу. Каталог стандартної бібліотеки підтримує workloadSchema у відповідності до можливостей provider. Поле є задокументованим контрактом; ніщо інше його не читає. Самі тіла Workload валідуються щодо вбудованої схеми Workload, що належить платформі, а не щодо цього поля окремого provider.

spec.provider.wellKnownAnnotations

Упорядкований масив, що перелічує платформно-нативні загальновідомі ключі анотацій — ті, що належать до зарезервованого простору імен aggrega.ai/, — які читає цей provider, разом із поведінкою, що застосовується за відсутності кожного з них. Кожен запис містить key (анотацію, яку читає provider, напр. aggrega.ai/namespace), purpose (чим керує анотація, коли вона присутня), необов’язковий defaultBehavior (що робить provider, коли анотація відсутня) і необов’язковий scope, що перелічує, де provider читає ключ, — sourced, synthesized або artifactsStandalone, тобто види вхідних даних Recipe, або boundary для ключа, який читається один раз на межу. key і purpose обов’язкові; записи зберігають порядок, заданий автором.

Поле є заявою provider про підтримку, і компілятор читає його у два способи. Запис, чий scope називає вид вхідних даних, якого не заявляє власне contract.inputKinds блоку, суперечить цій заяві, і Plugin відхиляється із зазначенням ключа та області. А коли збірка рендерить через цей provider, анотація aggrega.ai/, яку жоден запис не охоплює для жодного виду вхідних даних, оголошеного рендерингом, викликає попередження, що називає ключ, provider і ці види вхідних даних; значення все одно проходить без змін, і збірка не зупиняється. За відсутності поле нічого не заявляє, і для цього provider таке попередження не виникає. Валідація схеми перевіряє лише форму кожного запису (ключ належить до простору імен aggrega.ai/, purpose присутнє); вона відрізняється від перевірки під час виконання, яка регулює прив’язування значення до зарезервованого простору імен.

metadata:
pluginType: provider
spec:
abiVersion: v1beta1
provider:
capabilities: # recorded by `aggrega plugin gen-catalog` from describe()
- helm
workloadSchema: |
# how the Workload kind translates to this provider's native output
...
wellKnownAnnotations:
- key: aggrega.ai/namespace
purpose: Overrides the target namespace the provider renders into.
defaultBehavior: Renders into the boundary's default namespace.

Набори анотацій окремих provider і вміст workloadSchema, які постачають provider стандартної бібліотеки, задокументовано в ../providers/well-known-annotations.md, ../providers/helm.md, ../providers/helm-chart.md і ../providers/compose.md.

spec.provider.readsNoWellKnownAnnotations

Оголошує, що цей provider не читає жодного з нативних для платформи загальновідомих ключів анотацій. Це заява про підтримку, що не охоплює жодного ключа, і вона каже те, чого не каже пропуск і її, і wellKnownAnnotations: відсутня заява — це мовчання, тоді як ця — власне твердження provider, що він нічого не читає в зарезервованому просторі імен aggrega.ai/. Збірка, що рендерить через такий provider, попереджає про кожну анотацію aggrega.ai/, яка доходить до рендерингу, називаючи ключ, provider і види вхідних даних, які оголошує рендеринг; значення все одно проходить без змін, і збірка не зупиняється.

Можна записати лише true, тож пропуск поля залишається єдиним способом нічого не заявляти. Його не можна записати разом із wellKnownAnnotations: provider, який читає деякі з ключів, натомість перелічує їх там. Обидві відмови — на рівні схеми, тож Plugin відхиляється під час читання.

spec:
provider:
capabilities:
- terraform
readsNoWellKnownAnnotations: true

Його оголошує provider terraform зі стандартної бібліотеки; ../providers/terraform.md пояснює, що це означає для сутності Release, яку рендерять через нього.

spec.provider.contract

Самостійно задекларований контракт поведінки рендерингу під час компіляції для плагіна, що рендерить як провайдер: типи вхідних даних, які він рендерить, як він збирає вивід окремих вузлів групи диспетчеризації, пару розділювачів шаблонів, яку він застосовує до імпортованих файлів артефактів, чи може один завантажений екземпляр обслуговувати кожен перехід, чи враховує він записи omit і чи приймає він файли, які Recipe додає до спільного виводу своєї межі. Він розташований поруч із capabilities у тому самому блоці, але відповідає на інше питання: список можливостей визначає, які можливості обслуговує цей плагін, а контракт — як він їх рендерить. aggrega plugin gen-catalog записує його з власного самозвіту плагіна describe(), а хост звіряє його з цим самозвітом під час публікації та завантаження; розбіжність зупиняє роботу. Відсутність блоку означає, що контракт поведінки рендерингу не задекларовано, і звіряння порівнює лише заяви окремих експортів. Усі поля необов’язкові.

ПолеДія
inputKindsЯкі з трьох типів вхідних даних Recipe рендерить плагін, кожен як незалежна булева заява: sourced (набір вихідних файлів — чарт, модуль, файл compose), synthesized (синтезоване Workload) і artifactsStandalone (самостійний вузол з імпортованими документами артефактів без джерела чи workload). Хост перевіряє тип вхідних даних вузла за цим набором.
boundaryAssemblyЯк плагін поєднує вивід рендерингу окремих вузлів групи диспетчеризації: none записує вивід кожного вузла безпосередньо за шляхом диспетчеризації; merge згортає фрагменти окремих вузлів в один документ; nest розміщує вивід кожного вузла на його власній позиції в загальній структурі. Відсутність поля означає відсутність заяви щодо збирання.
artifactDelimitersПара розділювачів Go-шаблонів, яку плагін застосовує до імпортованих файлів артефактів, у вигляді left і right. Відсутність поля означає типову пару {{/}}; плагін, чий цільовий синтаксис конфліктує з цією парою, декларує альтернативну пару (наприклад, [[/]]).
reusableInstanceЧи може один завантажений екземпляр плагіна обслуговувати кожен перехід рендерингу, збирання й валідації під час збирання замість нового екземпляра для кожного переходу. Декларується як true лише тоді, коли плагін не зберігає стан між переходами, тож один екземпляр видає побайтово ідентичний вивід незалежно від того, чи його використано повторно, чи завантажено заново. Відсутність (false) завантажує новий екземпляр для кожного переходу, ізолюючи плагін, що за своєю будовою має стан. aggrega build --verify-determinism доводить стабільність виводу повторно використовуваного плагіна, рендерячи кожен вузол двічі й зупиняючись за будь-якої розбіжності.
omitsЧи враховує плагін записи omit — записи, що називають відрендерені одиниці, які слід виключити з виводу вузла: він виключає з того, що рендерить, кожну одиницю, якій відповідає запис, і повідомляє, скільком одиницям відповідав кожен запис. Значення фіксує заяву, яку повідомляє describe() плагіна, тож true правильне лише для плагіна, який це повідомляє, а значення, що відрізняється від звіту, зупиняє роботу. Відсутність (false) означає, що така підтримка не задекларована.
boundaryArtifactsЧи приймає ціль плагіна файли, які Recipe додає до спільного виводу межі, у якій він рендерить, згідно з spec.boundary.artifacts сутності Recipe: компілятор записує кожен такий файл один раз поруч із тим, що плагін збирає для межі, а ціль читає його як частину цього виводу. Значення фіксує заяву, яку повідомляє describe() плагіна, а значення, що відрізняється від звіту, зупиняє роботу. Відсутність (false) означає, що така підтримка не задекларована, і Recipe, що декларує цей блок для цього плагіна, відхиляється ще до будь-якого рендерингу.
metadata:
pluginType: provider
spec:
provider:
capabilities: # recorded by `aggrega plugin gen-catalog` from describe()
- helm-chart
contract:
inputKinds:
sourced: true
synthesized: false
artifactsStandalone: false
boundaryAssembly: nest
artifactDelimiters:
left: "[["
right: "]]"
reusableInstance: true

spec.pipelineStep

Блок кроку конвеєра для плагіна pluginType: pipeline-step. Його єдине поле, capabilities, називає провайдерів, відрендерений вивід яких крок плагіна вміє перетворювати, — назви можливостей, як-от helm або compose. Крок пишуть під форму виводу одного провайдера за раз, тому список називає провайдерів, про яких повідомляє сам плагін; записи зберігають порядок, у якому їх записано. Блок присутній лише в плагінах кроків конвеєра.

Блок є придатним для читання каталогом записом цього твердження: aggrega plugin gen-catalog записує його із власного самозвіту плагіна describe(), і автор може звузити його перед публікацією. Механізм примусового застосування зчитує те саме твердження з плагіна: коли крок зачіпає область, збірка зупиняється, якщо провайдер, що рендерить документи цієї області, не входить до тих, які заявляє плагін. Порожній або відсутній список не оголошує жодного твердження про сумісність, тож жодна область не допускає цей крок.

metadata:
pluginType: pipeline-step
spec:
abiVersion: v1beta1
pipelineStep:
capabilities: # recorded by `aggrega plugin gen-catalog` from describe()
- helm
- compose

spec.parser

Блок парсера для плагіна pluginType: parser. Його єдине поле, capabilities, називає вихідні формати, які плагін перетворює на канонічне структуроване дерево; кожен записується як parse:<format>. Префікс є частиною запису, тому плагін, що читає кілька форматів, перелічує по одному запису на кожен формат. aggrega plugin gen-catalog записує список із власного describe() плагіна, автор може звузити його перед публікацією, а записи зберігають порядок, у якому їх записано. Блок присутній лише в плагінах-парсерах.

Запитаний формат зіставляється з парсером, список якого містить відповідний запис. Формат, який не оголошує жоден парсер, зупиняє збірку, а формат, оголошений більш ніж одним плагіном-парсером, зупиняє її як неоднозначний із переліком кандидатів — резервного варіанта немає, бо парсер не має типового варіанта без конфігурації, до якого можна було б повернутися. Порожній або відсутній список не оголошує жодного формату, тож плагін нічого не розбирає.

metadata:
pluginType: parser
spec:
abiVersion: v1beta1
parser:
capabilities: # recorded by `aggrega plugin gen-catalog` from describe()
- parse:hcl
- parse:toml

spec.importer

Блок імпортера для плагіна pluginType: importer. Його поле capabilities називає сторонні вихідні формати, які плагін перетворює на чернеткові авторські файли Aggrega; кожен записується як import:<format>. Префікс є частиною запису, тож плагін, що обробляє кілька форматів, перелічує по одному запису на формат. aggrega plugin gen-catalog записує список із власного describe() плагіна, автор може звузити його перед публікацією, а записи зберігають порядок, у якому їх записано. Блок присутній лише в плагінах-імпортерах.

Запитаний формат імпорту зіставляється з імпортером, список якого містить відповідний запис. Формат, який не оголошує жоден імпортер, зупиняє імпорт, а формат, оголошений кількома плагінами-імпортерами, зупиняє його як неоднозначний із переліком кандидатів, якщо тільки запис plugins.importer у конфігурації робочого простору не підключає один із них — тоді запускається саме він. Порожній або відсутній список не заявляє жодного формату, тож плагін нічого не імпортує.

Його поле detect записує сигнатури, за якими розпізнається джерело цих форматів, коли імпорт не називає формату. Воно належить машині, як і записи хост-функцій і команд: його виводять із того, що повідомляє describe() плагіна, коли сутність генерується з плагіна, у порядку, в якому плагін оголошує сигнатури, і автор його не пише. Кожна сигнатура називає:

  • syntax — синтаксичний формат, у якому розбирається джерело, тобто формат, який плагін-парсер оголошує як parse:<syntax>, наприклад json або yaml.
  • files — необов’язкові шаблони імен файлів, які зіставляються з кінцем імені джерела: шаблон з одного сегмента — з власним ім’ям файлу, шаблон із кількох сегментів, розділених скісною рискою, — з такою самою кількістю кінцевих сегментів його шляху, тож .vscode/mcp.json відповідає файлу з назвою mcp.json у каталозі з назвою .vscode. *, ? і [...] зіставляються в межах сегмента. Якщо поле відсутнє, сигнатура застосовується до джерела, що є одним файлом, хоч як би він називався, і до жодного файлу каталогу. Шаблони сигнатур імпортера також визначають, які файли каталогу передає йому aggrega import.
  • match — предикати, яким має відповідати розібране дерево, усім без винятку. Кожен має path — ключі, з’єднані крапками від вершини дерева, де сегмент-ціле число вибирає позицію в масиві; is — одне з present, absent, object, array, string, number і boolean; і необов’язково equals — рядок, яким має бути значення, або prefix — рядок, з якого воно має починатися, — щонайбільше одне з двох.

Коли імпорт не називає формату, із джерелом зіставляються сигнатури кожного імпортера з каталогу робочого простору — включно з усіма версіями — і основних імпортерів компілятора. Джерело розбирається один раз для кожного синтаксису, у якому його читає сигнатура, що застосовується до його імені, через парсер, який каталог робочого простору надає для цього синтаксису, — або, для синтаксису, для якого каталог не надає парсера, через парсер, вбудований у сам компілятор, — а джерело, що не розбирається в певному синтаксисі, не відповідає жодній сигнатурі, яка його називає. Каталог зіставляється через свої файли: кожна сигнатура перевіряється на файлах каталогу, які вибирають її шаблони, в порядку імен, а сигнатура без шаблонів не застосовується до жодного з них. Джерело, якому відповідає сигнатура, розпізнається як кожен формат, який оголошує її імпортер. Якщо розпізнано рівно один формат, джерело читається саме в ньому. Джерело, якому не відповідає жодна сигнатура, відхиляється із запитом формату та переліком форматів, які оголошують імпортери, — або, для каталогу, із запитом одного з його файлів окремо чи формату, імпортер якого оголошує шаблони файлів, з переліком лише таких форматів; джерело, розпізнане як кілька форматів, відхиляється з їх переліком і умовою More than one importer recognises the source (Джерело розпізнає більше ніж один імпортер). Отже, в імпортера, що оголошує більше ніж один формат, кожне джерело, якому відповідають його сигнатури, відхиляється як неоднозначне, а імпортер, джерела якого мають розпізнаватися, обслуговує один формат.

Якщо сутність записує detect, воно має дорівнювати тому, що повідомляє describe() плагіна, сигнатура за сигнатурою і в тому самому порядку: під час завантаження імпортера плагін, чий звіт відрізняється, відхиляється із зазначенням importer.detect, і так само під час його публікації. Сутність, яка не записує detect, нічого не стверджує і не порівнюється, тож вона завантажує будь-які сигнатури, про які повідомляє describe() її плагіна, а до форматів її імпортера тоді можна дістатися, лише назвавши їх.

metadata:
pluginType: importer
spec:
abiVersion: v1beta1
importer:
capabilities: # recorded by `aggrega plugin gen-catalog` from describe()
- import:langflow
detect:
- syntax: json
match:
- path: data.nodes
is: array

spec.signature

Необов’язковий описовий вказівник на підпис, долучений до плагіна. Цей блок суто документаційний: він фіксує для читачів каталогу, де зберігається підпис і як його створено; сам по собі він не допускає плагін. Перевірку, що справді діє, виконує політика довіри окремого реєстру, яка застосовується під час pull: підпис завантажується як OCI referrer, перевіряється за довіреними ідентичностями реєстру або закріпленим ключем і записується в lock-файл як перевірений факт. Реєстр, що вимагає підписів, зупиняє pull, коли обов’язковий підпис відсутній, недовірений або недійсний.

  • type — схема підпису. Підтримувана схема — sigstore-cosign. Обов’язкове, коли блок присутній.
  • signatureRef — посилання OCI referrer на долучений пакет підпису, для документації та виявлення. Відсутнє, коли підпис виявляється переліченням referrer під час pull, а не закріплюється тут.
  • publicKeyRef — вказівник на відкритий ключ, яким створено підпис, для підпису з ключем. Відсутність означає безключовий підпис (на основі OIDC-ідентичності), який перевіряється за довіреними ідентичностями реєстру.

spec.runtime

Необов’язкові обмеження виконання, які хост застосовує під час завантаження й запуску плагіна. Вихідний мережевий доступ не є полем для авторингу: плагін ніколи не звертається до мережі під час збирання — це межа ahead-of-time, — тому поля зі списком дозволених хостів тут немає. Віддалений вміст, потрібний плагіну, надходить через опосередкований хостом канал зовнішніх вхідних даних із закріпленим дайджестом, записаний у lockfile сутності Release, і ніколи через фоновий мережевий доступ; посібник розробника описує обгортку для отримання даних і дисципліну закріплення.

ПолеДія
maxMemoryPagesОбмежує лінійну пам’ять плагіна в сторінках Wasm (64 KiB на сторінку). Нуль або відсутність значення застосовує типове обмеження платформи, тож завантаження ніколи не є необмеженим; підключення, якому потрібно більше, збільшує це значення.
timeoutMsОбмежує, скільки часу власний код плагіна може виконуватися під час одного виклику, у мілісекундах, без урахування часу, проведеного всередині функцій хоста, які він викликає. У Linux вимірюється процесорний час, тож час очікування на процесор на завантаженій машині не враховується; в інших системах вимірюється фактичний час. Перший виклик щойно завантаженого плагіна також враховує власний запуск плагіна. Нуль або відсутність значення застосовує типове обмеження платформи, тож виклик ніколи не є таким, що його неможливо скасувати; підключення, яке виконується довше, збільшує це значення.
hostFunctionsІмена функцій хоста, які імпортує плагін. Виводиться машинно й доступне лише для читання — не заповнюйте його: aggrega plugin sync зчитує функції хоста з секції імпорту .wasm і записує це поле, публікація відхиляє запис, що відрізняється від бінарного файлу, а значення відображає опублікований бінарний файл і перевіряється за курованим списком дозволених. Хост реєструє саме цей набір, надаючи кожному плагіну мінімально привілейовану поверхню хоста, потрібну його бінарному файлу; під час pull мітка знову виводиться й перевіряється за бінарним файлом. Щоб переглянути значення до публікації, виконайте aggrega inspect --plugin <file.wasm>.
configKVPlugin-специфічна конфігурація, яку середовище виконання передає плагіну під час запуску, у вигляді пар ключ/значення типу рядок-рядок. Записи зберігають порядок, заданий автором, тож згенерований запис байт-у-байт ідентичний між запусками. Якщо поле відсутнє, діє типова порожня конфігурація середовища виконання.

spec.exports

Експорти, які пропонує плагін, кожен зі своєю оголошеною можливістю, у вигляді впорядкованого списку, що зберігає порядок автора. Експорт — це одна іменована точка входу, до якої хост спрямовує виклики (наприклад, render_node, lint_naming, step); блок можливостей для кожного експорту визначає, що робить цей експорт, у тому вигляді, у якому aggrega plugin gen-catalog записує його із самозвіту плагіна describe(), і хост звіряє його з цим самозвітом під час публікації та під час завантаження. Відсутність поля означає, що авторська поверхня експортів не оголошена.

ПолеДія
nameІм’я експорту в ABI — ім’я, до якого хост спрямовує виклики. Обов’язкове для кожного запису.
operatesОперація конвеєра, яку виконує експорт: patch (змінити наявний відрендерений документ) або emit (додати новий документ). Хост звіряє значення із самозвітом плагіна; це перевірювана заява про можливість, а не перемикач диспетчеризації — операцію, яку виконує крок, визначає результат, повернутий гостьовим модулем. Відсутність поля означає відсутність заяви про операцію.
scopeКорінь документів, з яким працює експорт: own (власні відрендерені документи вузла) або host (документи компонента, до якого приєднано FeatureRecipe рівня компонента). Хост зчитує оголошену область перед кроком, щоб забезпечити сумісність із провайдером, який рендерить цю область. За відсутності поля використовується own.
selectorДовільний опис для людей того, на що діє експорт (наприклад, workloads carrying a pod template). Документація для читачів каталогу та для поверхні inspect; компілятор його не інтерпретує.

spec.commands

Дієслова верхнього рівня aggrega <command>, які додає плагін типу cli, у вигляді впорядкованого списку, що зберігає порядок, оголошений у самозвіті плагіна describe(). Поле належить машині й доступне лише для читання — не заповнюйте його вручну. aggrega plugin sync зчитує набір команд із самозвіту плагіна describe() і записує його сюди, тож команди, які встановлює CLI-плагін, можна прочитати із сутності без завантаження .wasm. Плагін, тип якого не cli, не додає команд і записує порожній список. Хост встановлює саме цей набір; якщо записаний набір розходиться із самозвітом плагіна describe(), завантаження зупиняється, а публікація відхиляє набір, не синхронізований із двійковим файлом, і пропонує авторові записати його повторно. Щоб повторно синхронізувати запис після зміни плагіна, виконайте aggrega plugin sync.

Кожен запис команди містить:

ПолеДія
nameДієслово команди, яке реєструє хост, — токен aggrega <name>, який викликає оператор, і дискримінатор, який хост передає плагіну під час виклику, щоб один плагін, що обслуговує кілька команд, міг визначити, яку команду викликано. Обов’язкове для кожного запису.
descriptionОднорядковий короткий текст довідки команди, що показується у списку команд і у виводі довідки. Лише документація; хост на нього не реагує.
flagsПрапорці команди в оголошеному порядку. Кожен запис реєструє один прапорець команди, щоб aggrega help <command> показувала його так само, як прапорець основної команди. Команда без прапорців залишає поле порожнім.

Кожен запис flags оголошує один прапорець:

ПолеДія
nameДовге ім’я прапорця — токен --name, який оператор передає в командному рядку. Обов’язкове для кожного запису.
shorthandНеобов’язковий короткий псевдонім прапорця — форма -x, яку оператор може передати замість довгого імені, — у вигляді однієї літери або цифри ASCII. Відсутність поля означає, що прапорець не має короткого псевдоніма.
descriptionОднорядковий текст довідки прапорця, що показується у виводі довідки команди. Необов’язкова документація; хост її не перевіряє і на неї не реагує.
typeТип значення прапорця — string, bool або int — і вид прапорця, яким його показує довідка. За відсутності поля прапорець показується як рядковий.
defaultЗначення прапорця за замовчуванням, коли оператор його не передає, записане як рядок. Для прапорця bool або int це значення відповідного типу. Відсутність поля означає, що прапорець не оголошує значення за замовчуванням.

Плагін CLI оголошує свої команди та їхні прапорці в describe(); хост реєструє саме цю поверхню і показує прапорці кожної команди в aggrega help <command> так само, як прапорці вбудованої команди.

Хост перевіряє кожен прапорець, оголошений плагіном, коли додає команди плагіна, і плагін з помилковими оголошеннями пропускається, а не додається: жодна з його команд не реєструється, попередження називає плагін, команду, прапорець і те, що з ним не так, а всі інші команди — вбудовані чи з іншого плагіна — продовжують працювати. Оголошення помилкове, коли:

  • прапорець не має імені або команда оголошує те саме ім’я двічі;
  • короткий псевдонім є чимось іншим, ніж одна літера або цифра ASCII, або команда оголошує той самий короткий псевдонім для двох прапорців;
  • ім’я або короткий псевдонім повторює прапорець, який уже має кожна команда aggrega, — --help, його -h і глобальні прапорці, як-от --offline і --config;
  • тип є чимось іншим, ніж string, bool або int;
  • значення за замовчуванням не розбирається як тип прапорця — maybe для bool, three для int.

Односимвольна форма shorthand і три значення type також є частиною схеми цієї сутності, тож сутність Plugin, що записує будь-яке інше значення, відхиляється під час завантаження каталогу. Те, що ім’я або короткий псевдонім трапляється один раз на команду, що жоден не повторює прапорець, який має кожна команда, і що значення за замовчуванням розбирається як його тип, перевіряє лише хост. Перевірка визначає, чи може хост оголосити прапорець для довідки в записаному вигляді; вона не бачить, чи читає плагін оголошені ним прапорці, бо плагін сам розбирає свої аргументи.

metadata:
pluginType: cli
spec:
abiVersion: v1beta1
# commands is recorded by `aggrega plugin sync` from the plugin's describe() — do not author it.
commands:
- name: greet
description: Print a friendly greeting
flags:
- name: name
shorthand: n
description: Who to greet
type: string
default: world

Перегляд сутності Plugin

aggrega inspect <path-to-Plugin.yaml> відображає файл Plugin: його ідентичність і тип сокета, можливості, які оголошує його блок, таблицю можливостей для кожного експорту в порядку автора, обмеження середовища виконання, а з --detail — також вказівник на підпис і ключі конфігурації середовища виконання. До сутності Plugin можна звернутися за шляхом до файлу або за її координатою <pluginType>/<name> у каталозі. Див. ../cli/aggrega-inspect.md.

Перехресні посилання

  • Посібник розробника Wasm-плагінів — повний робочий процес автора: describe(), заявлення можливостей, обмеження середовища виконання, життєвий цикл, підписування, версіонування.
  • Контракт Wasm-плагінів — точки сокетів, до яких під’єднується плагін, і форми їхніх вхідних і вихідних даних.
  • entities/featurerecipe.md — поверхня pipeline: сутності FeatureRecipe, яка посилається на плагін за URI сутності.
  • cli/aggrega-lint.md — лінтер публікації, критерії підвищення версії та забезпечення незмінності, які регулюють публікацію сутності Plugin.