Посібник розробника Wasm-плагінів
Це канонічний посібник зі створення WebAssembly-плагіна (Wasm) для Aggrega та його публікації як сутності каталогу. Він від початку до кінця пояснює контракт автора плагіна: що таке плагін, як плагін описує себе хосту, як створювати його експорти та заявки на можливості, які обмеження середовища виконання та функції хоста застосовує хост, сутність Plugin, що переносить плагін у каталог, як сутність Recipe або FeatureRecipe посилається на плагін, а також життєвий цикл publish→pull→build, який перетворює файл .wasm на диску на перевірений, закріплений за дайджестом артефакт, що його споживає збірка.
Супровідна сторінка plugin-contract.md документує сокети — точки конвеєра, до яких під’єднуються плагіни, і форми вхідних та вихідних даних, які кожен сокет споживає й створює. Цей посібник документує плагін — сутність, поверхню можливостей і життєвий цикл. Прочитайте сторінку контракту, щоб дізнатися, на який сокет націлений ваш плагін; прочитайте цю сторінку, щоб дізнатися, як його створити й випустити.
Щоб пройти все завдання на прикладі, а не за довідкою, перегляньте створення провайдера: там від початку до кінця будується один невеликий гостьовий модуль провайдера — дескриптор, збірка, сутність, під’єднання та рендеринг, результат якого можна прочитати, — включно з відмовою, яку зазвичай отримує перша чернетка, і тим, як її прочитати.
1. Що таке Wasm-плагін
Wasm-плагін — це модуль WebAssembly, який розширює компілятор у визначеному сокеті. Бінарний файл хоста на Go не містить логіки, специфічної для хмари чи інфраструктури; уся предметна логіка — рендеринг шаблонів, перетворення форматів, оцінювання політик, лінтинг — міститься в плагінах. Хост оркеструє конвеєр і передає корисне навантаження кожного сокета через межу ABI гостьовому модулю; гостьовий модуль виконує предметну роботу й повертає результат у формі, визначеній для цього сокета. Корисне навантаження й результат кожного сокета передаються як канонічний CBOR, за двома винятками: CLI-плагін отримує вектор аргументів як текст JSON і відповідає кодом виходу та текстом, який він виводить потоком, а самозвіт describe є текстом JSON. Розділ кожного сокета в контракті плагінів вказує його кодування, а гостьовий модуль читає й записує його через точки входу, які вже має тип корисного навантаження його набору, тож жоден гостьовий модуль не розбирає байти вручну.
Плагін виконується за брандмауером чистоти попередньої (ahead-of-time) компіляції. Хост завантажує й виконує модуль через вбудоване середовище виконання Wasm у конфігурації з забороненими можливостями: без мережевих сокетів, без файлової системи, без змінних середовища, зі скинутим stdio та зі спостережуваним системним годинником, зафіксованим на моменті, незмінному для збірки. Будь-який виклик вводу-виводу, який намагається здійснити гостьовий модуль, завершується помилкою на межі виклику, тож плагін не може звернутися до стану під час виконання. Пишіть плагіни з урахуванням цього брандмауера: плагін перетворює передане йому корисне навантаження й повертає результат, який хост використовує дослівно, а детермінізм — ваша відповідальність: однакові вхідні дані мають давати однакові вихідні байти. Єдиний дозволений канал для віддаленого вмісту — опосередковане хостом отримання зовнішніх вхідних даних (розділ 4), яке надає байти за дисципліною закріплення за дайджестом, а не дає гостьовому модулю живий доступ до мережі.
Сокети, на які може бути орієнтований плагін, — серед них шлюз мутацій під час побудови топології, шлюз валідації під час статичного аналізу, конвеєр FeatureRecipe, позасмуговий лінтер і сокет рендерингу провайдера, — а також форми вхідних і вихідних даних кожного сокета задокументовано в plugin-contract.md. Який сокет обслуговує плагін — це одне значення, яке він оголошує в metadata.pluginType, а повний набір значень, які приймає це поле, наведено в довідковому записі для нього в entities/plugin.md §«metadata.pluginType». У прикладах цього посібника використано provider (рендерить вузли IR в артефакти, рідні для провайдера), linter (перевіряє написаний вміст і видає діагностику) та pipeline-step (крок у pipeline: сутності FeatureRecipe або Recipe, що накладає патчі на відрендерений набір документів).
Гостьовий модуль для хоста пишеться за допомогою тримовного набору для розробки плагінів (PDK) — Go, Rust або TypeScript. PDK обгортає базовий інструментарій Wasm будівниками з типами Aggrega для форм вхідних і вихідних даних, які передає кожен сокет.
2. Самозвіт describe()
Кожен плагін експортує функцію describe(), яка повертає самозвіт плагіна: тип(и) сокетів, які він реалізує, версію ABI, на яку він орієнтований, можливості, які він заявляє (їх тлумачать відповідно до типу сокета: назви можливостей для провайдера чи кроку конвеєра і формати джерел із префіксами для парсера чи імпортера), хост-функції, які він імпортує, а також можливість кожної точки входу, яку він пропонує, окремо для кожного експорту. describe() — це власний опис плагіна: що він собою являє і що робить.
Самозвіт є опорою моделі довіри. Сутність Plugin, яка вносить плагін до каталогу (розділ 5), повторює ті самі факти як авторські заяви, і хост звіряє заяви сутності з виводом describe() плагіна у два моменти: під час публікації, до того як будь-які байти потраплять до реєстру, і під час завантаження, до запуску плагіна. Розбіжність призводить до явної зупинки. Сутність — це зрозуміла людині поверхня, видима в каталозі; describe() — це машинне джерело істини, з яким хост її звіряє. Пишіть обидва так, щоб вони узгоджувалися; перехресна перевірка існує саме для того, щоб виявити випадок, коли вони розходяться. Вона перевіряє те, що сутність заявляє, а не те, що вона пропускає: сутність, яка заявляє менше, ніж повідомляє бінарний файл, — наприклад, залишена після перезбирання, що додало експорт, — однаково завантажується, хоча вже не описує всього, що робить бінарний файл.
3. Створення експортів і їхніх заявлених можливостей
Плагін пропонує один або кілька експортів — іменованих точок входу, до яких хост спрямовує виклики (наприклад, render_node, lint_naming, step). Кожен експорт містить блок можливостей: заяву автора про те, що робить цей експорт. Можливість експорту має чотири поля:
name— ABI-ім’я експорту, ім’я, до якого хост спрямовує виклики. Обов’язкове.operates— операція конвеєра, яку виконує експорт:patch(змінити наявний відрендерений документ) абоemit(додати новий документ). Це задекларована заява про можливість. Хост звіряє її із самозвітомdescribe()плагіна під час публікації та під час завантаження, тож заява, записана автором у сутності, і власний опис плагіна мають збігатися. Це перевірювана заява про експорт, а не перемикач диспетчеризації: під час рендерингу операцію, яку фактично виконує крок, визначає результат, повернений гостьовим модулем, а не це поле. Відсутність поля означає відсутність заяви про операцію.scope— корінь документів, з яким працює експорт:own(власні відрендерені документи вузла) абоhost(документи компонента, до якого приєднано FeatureRecipe з областю дії компонента). Перед запуском плагіна кроку конвеєра хост зчитує задекларовану область дії експорту кроку й перевіряє, що провайдер, який рендерить документи цієї області, присутній уspec.pipelineStep.capabilitiesплагіна (розділ 5): експорт з областюownперевіряється щодо провайдера, який рендерить власні документи вузла, експорт з областюhost— щодо провайдера компонента-хоста, а порожня область для цієї перевірки за замовчуванням вважаєтьсяown. Це шлюз сумісності з провайдером, що виконується перед кроком; документ, якого фактично торкається гостьова операція, називається для кожної операції окремо в результаті, поверненому гостьовим модулем, а не визначається цим задекларованим полем. За відсутності поля типове значення —own.selector— довільний, зрозумілий людині опис того, на що діє експорт (наприклад,workloads carrying a pod template). Це документація для читачів каталогу та для поверхніaggrega inspect; компілятор його не інтерпретує.
Записуйте експорти в тому порядку, у якому їх слід читати; записи зберігають авторський порядок у сутності та в inspect. Плагін без записаних експортів не декларує поверхні експортів — це допустимо для плагіна, чий сокет не потребує заяви про можливості для кожного експорту.
4. Обмеження виконання та функції хоста
Сутність плагіна може містити необов’язковий блок runtime, який обмежує те, як хост завантажує та виконує плагін.
Обмеження пам’яті та часу. maxMemoryPages обмежує лінійну пам’ять плагіна у сторінках Wasm (64 KiB на сторінку); timeoutMs обмежує, як довго власний код плагіна може виконуватися під час одного виклику, у мілісекундах. Час, проведений усередині функцій хоста, які викликає плагін, до нього не зараховується. У Linux вимірюється процесорний час потоку, що виконує гостьовий код, тож час, який гість чекає на процесор на завантаженій машині, також не зараховується; в інших системах це реальний час, що минув. Перший виклик щойно завантаженого плагіна також враховує одноразову ініціалізацію середовища виконання гостьової мови, яка відбувається всередині цього виклику. Обидва обмеження необов’язкові та мають значення за замовчуванням: нуль або відсутність значення застосовує типове обмеження платформи. Завантажувач обмежує кожен плагін типовим значенням платформи, коли сутність не оголошує жодного, тож завантаження ніколи не буває необмеженим, а виклик завжди можна скасувати. Підвищуйте обмеження в сутності, коли підключенню справді потрібно більше пам’яті або більше часу, ніж дозволяє типове значення.
Функції хоста. hostFunctions фіксує імена функцій хоста, які імпортує плагін. Це поле, що виводиться машиною, — не заповнюйте його. aggrega plugin sync зчитує функції хоста безпосередньо із секції імпорту .wasm і записує поле у файл сутності за вас, а публікація повторно виводить їх із бінарного файлу й відхиляє сутність, запис якої відрізняється; тож плагін отримує саме ті функції хоста, які його бінарний файл справді імпортує, перевірені за впорядкованим списком дозволених (імпорт поза цим списком явно відхиляється). Цей запис є знімком опублікованого бінарного файлу так само, як адресоване за вмістом посилання plugin: є знімком опублікованих байтів: воно відображає бінарний файл на момент публікації та повторно виводиться й перевіряється під час отримання плагіна. Щоб побачити функції хоста, які імпортує локальний .wasm, перед публікацією — значення, яке записує aggrega plugin sync, — виконайте aggrega inspect --plugin <file.wasm>.
Впорядкований набір функцій хоста. Три функції хоста мають загальне призначення: aggrega_log (рівень і повідомлення, що виводяться одним рядком журналу в журнал хоста), aggrega_emit_warning (код, повідомлення та шлях, що накопичуються як структуроване попередження, яке хост показує після виклику) і aggrega_fetch_external_input (URL, на який відповідають байтами вхідних даних згідно з описаною нижче дисципліною закріплення). PDK обгортає всі три в кожній мові — Go: aggrega.Log, aggrega.EmitWarning, aggrega.FetchExternalInput; Rust: log, emit_warning, fetch_external_input; TypeScript: log, emitWarning, fetchExternalInput — тож гість викликає типізовану функцію, а не сирий ABI. Зворотні виклики джерела та розбору — для гостя, який читає фрагменти отриманого джерела або отримує розібране дерево через хост, — і кодування, яке несуть слоти кожного зворотного виклику, перелічено в plugin-contract.md.
Локальний вміст джерела надходить через хост — ніколи з файлової системи. Плагін рендерингу провайдера ніколи не читає своє джерело з диска; виклик файлової системи завершується помилкою на межі виклику. Хост передає гостю всередині корисного навантаження рендерингу перелік джерела — шлях кожного запису відносно кореня джерела та ознаку, чи це каталог, у відсортованому порядку, без вмісту файлів, — а гість застосовує до нього власну логіку розкладки й потім зчитує саме ті файли, які вибирає, через зворотні виклики джерела, що повертають байти, які хост читає під коренем джерела. Форми корисного навантаження для кожного сокета та зворотні виклики задокументовано в plugin-contract.md.
Віддалений вміст надходить через отримання зовнішніх вхідних даних. Плагін, якому потрібен віддалений вміст — архів чарту, віддалений документ схеми, — викликає обгортку отримання з PDK. На рівні протоколу гість передає URL до aggrega_fetch_external_input як текст UTF-8 і отримує одну відповідь у канонічному CBOR, що містить або отримані байти в сирому вигляді, або повідомлення про помилку поруч із її машинно-зіставним кодом; обгортка декодує відповідь у байти або помилку. Байти надходять точно в отриманому вигляді, включно з корисним навантаженням, яке не є коректним UTF-8, а корисне навантаження нульової довжини повертається як порожні байти, а не як помилка. Хост обслуговує URL згідно з дисципліною закріплення зовнішніх вхідних даних:
- URL, уже закріплений у lock-файлі сутності Release, обслуговується з локального сховища, адресованого за вмістом, і перевіряється за записаним дайджестом під час кожного читання. Відсутній у сховищі блоб повторно завантажується з мережі за записаним дайджестом — повторне завантаження, перевірене за дайджестом, не може змінити результат.
- Незакріплений URL відхиляється з помилкою, яка називає URL і спосіб виправлення. Збірка рендерить замикання, записане в її lock-файлі, тож жодна збірка не отримує незакріплене посилання, і немає налаштування, яке б це дозволяло.
- Закріплення відбувається під час розв’язання залежностей сутності Release:
aggrega pullрендерить Release, щоб з’ясувати, які зовнішні вхідні дані запитує її рендеринг, отримує кожні з них і записує їх у lock-файл поруч із закріпленнями залежностей. Тож робочий цикл автора плагіна такий: один раз розв’язати, а потім збирати офлайн скільки завгодно.
Дозволені схеми: https, http лише до локальних (loopback) хостів і oci (закріплення за дайджестом маніфесту). Lock-файл записує всі закріплені вхідні дані — їхній URL, дайджест sha256, розмір і плагіни, яким вони були потрібні, — тож повторна збірка обслуговує ті самі байти з локального сховища: відтворювано та офлайн після закріплення.
З Go PDK:
import "github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega"
chart, err := aggrega.FetchExternalInput("https://charts.example.com/postgresql-16.3.2.tgz")if err != nil { // The error names the URL and the remedy — an unpinned URL reports exactly // what to pin and how. Surface it as a render failure; do not mask it. return fmt.Errorf("fetching chart archive: %w", err)}Що завершується помилкою і чому.
- Виклик файлової системи або мережі завершується помилкою на межі виклику: гість не має заздалегідь відкритих каталогів і сокетів. Це стосується кожного шляху виконання коду, включно з бібліотечною залежністю, яка намагається прочитати файл, — натомість читайте джерело через зворотні виклики джерела.
- Імпорт із модуля поза
wasi_snapshot_preview1,extism:host/envіextism:host/userзавершується помилкою під час завантаження з діагностикою, що називає модуль та імпорт. Окремі імена функцій WASI в дозволеному модулі ніколи не блокуються — невикористані імпорти файлової системи та сокетів статично скомпонованого середовища виконання мови допустимі, бо називання імпорту нічого не надає. - Отримання URL, який lock-файл не закріплює, завершується помилкою, що називає URL; щоб виправити, виконайте
aggrega pull --release <release>, що закріплює всі зовнішні вхідні дані, які споживає рендеринг сутності Release, а потім збирайте.
Поля зі списком дозволених хостів для вихідного мережевого доступу немає. Плагін ніколи не звертається до мережі під час збірки — це межа компіляції наперед (ahead-of-time), — тож такого поля для заповнення не існує. Віддалений вміст надходить через описаний вище канал зовнішніх вхідних даних, опосередкований хостом і закріплений за дайджестом, а ніколи через загальний мережевий доступ.
Конфігурація. configKV — це відображення рядків у рядки, яке середовище виконання передає плагіну під час запуску. Записи зберігають авторський порядок, щоб виведений запис був побайтово ідентичним між запусками. За відсутності значення діє типова порожня конфігурація середовища виконання.
5. Сутність Plugin
Плагін потрапляє до каталогу як сутність Plugin — поверхня створення й метаданих плагіна. Сутність оголошує, чим є плагін, і вказує на артефакт .wasm; компілятор не інтерпретує поведінку плагіна й лише маршрутизує закріплене посилання, а середовище виконання Wasm виконує байти.
apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: aws-secrets-manager version: 1.2.0 pluginType: pipeline-stepspec: abiVersion: v1beta1 pipelineStep: 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Поля:
- Поля розташування артефакту немає навмисно. Сутність не містить вказівника на
.wasm, і схема його не приймає. Розташування артефакту плагіна виводиться з його ідентичності — координатиmetadata.pluginType/metadata.name, що утворює шлях репозиторіюplugin/<pluginType>/<name>, — плюс того реєстру, на який налаштовано робочий простір, тож немає розташування, яке треба писати, і жодного, яке можна вказати неправильно. Визначений дайджест вмісту записується для кожної сутності Release у lock-файлі цієї сутності Release, і збірка перевіряє завантажені байти за ним: ідентичність — у сутності, перевірені байти — у lock-файлі. metadata.version— реліз, який публікує сутність; він має дорівнювати власній версії походження збірки гостя, як її повідомляєdescribe(). Автор плагіна версіонує.wasmпід час збірки — збірка вписує версію в гостя, а збірка, що бере її з тегу релізу, вписує версію релізу лише на коміті, який цей тег позначає, — іmetadata.versionсутності називає той самий реліз. Етап публікації звіряє обидва значення й зупиняється в разі розбіжності, тож сутність завжди називає точну версію бінарного файлу, який постачає.aggrega plugin gen-catalog --plugin(див. нижче) копіює версію, яку повідомляє гість, у згенеровану сутність; це версія релізу, якщо гостя зібрано з позначеного тегом коміту. Обов’язкове.metadata.pluginType— тип сокета, який реалізує цей плагін, з-поміжprovider,linter,pipeline-step,governance,cli,parserтаimporter. Плагін реалізує рівно один. Він розташований в адресному блоці поруч ізnameіversionі задає сегмент<pluginType>виведеної координати. Обов’язкове.spec.abiVersion— версія ABI хоста/гостя, на яку орієнтується плагін. Прийнятним значенням єv1beta1; майбутня ревізія ABI додасть нове прийнятне значення. Обов’язкове.- Блок для вашого типу сокета з
capabilities— плагін оголошує, що він обслуговує, усередині блоку, який належить йогоmetadata.pluginType, і саме блок визначає значення запису.spec.provider.capabilitiesназиває можливості, які обслуговує провайдер (назви можливостей, як-отhelmабоcompose).spec.pipelineStep.capabilitiesназиває провайдерів, з виведенням яких сумісний ваш крок.spec.parser.capabilitiesназиває вихідні формати, які читає парсер, кожен у записіparse:<format>.spec.importer.capabilitiesназиває зовнішні формати, з яких імпортер створює чернетки сутностей, кожен у записіimport:<format>. Імпортер, написаний на Go, може взяти все, що не залежить від його формату, — оцінювання, рішення посилатися чи створювати чернетку, чернетки та їхнє рендерування, а також свої налаштування — з пакета імпортера в наборі Go,github.com/aggrega-ai/aggrega-pdk/go/pkg/importer. Плагінlinter,governanceабоcliне обслуговує жодної можливості й не містить жодного з чотирьох блоків. Записи зберігають авторський порядок, і кожен список є явною, перевіреною заявою: оголошуйте те, з чим ви справді зібрали й протестували плагін, адже споживач виконує розв’язання точно за переліченим. Для кроку конвеєра ця заява перевіряється під час рендерування — коли крок зачіпає область, збірка зупиняється, якщо провайдер, що рендерить документи цієї області, не входить до тих, які заявляє ваш плагін, — тож порожній список не відповідає жодному провайдеру й ніде не допускає крок. spec.signature— необов’язковий описовий вказівник на прикріплений підпис плагіна (розділ 8). Цей блок є лише документацією: він записує для читачів каталогу, де розташований підпис і як його створено; сам він плагін не допускає. Перевіркою, що діє насправді, є політика довіри кожного реєстру, застосована під час pull.spec.runtime— необов’язковий блок обмежень виконання з розділу 4. Автор пишеmaxMemoryPages,timeoutMsіconfigKV;hostFunctionsвиводиться машинно й записуєтьсяaggrega plugin sync, а публікація його перевіряє, — автор його не пише.spec.exports— заяви про можливості для кожного експорту з розділу 3 (name,operates,scope,selector).
Генерування сутності з вашого .wasm. Вам не потрібно вручну писати машинні частини сутності. aggrega plugin gen-catalog --plugin <file.wasm> читає самозвіт гостя describe() і створює з нього готову до публікації сутність Plugin разом із невеликим авторським накладенням, яке ви надаєте (ідентичність, обмеження виконання та будь-який блок провайдера). Генератор вписує поля, для яких джерелом істини є бінарний файл, — заяви експортів, контракт можливостей, дзеркало команд і запис функцій хоста — і копіює metadata.version з версії походження збірки у describe() гостя, а накладення надає лише те, чого бінарний файл не повідомляє. Це підтримуваний шлях для стороннього автора плагіна: зберіть і версіонуйте свій .wasm, а потім заново згенеруйте сутність, щоб її машинні поля залишалися синхронними з бінарним файлом. Версія — єдине скопійоване поле, яке називає реліз, а не факт про байти, тож генеруйте зі збірки коміту, який позначає тег релізу, — або, починаючи зі збірки розробки, задайте metadata.version у згенерованій сутності як реліз, перш ніж ставити тег на коміт, що її містить. Гостя без версії походження збірки неможливо згенерувати у версіоновану сутність — спершу версіонуйте гостя під час збірки.
.wasm поруч зі своєю сутністю. Поки ви створюєте плагін, ще не опубліковано нічого, що збірка могла б отримати, тому збірка читає .wasm плагіна з місця поруч із його сутністю Plugin у директорії каталогу, під іменем, похідним від типу плагіна й імені сутності: для pipeline-step/patch це pipeline-step--patch.wasm. Малі літери, цифри й більшість дефісів записуються в це ім’я як є; будь-який інший символ записується в екранованій формі, як і дефіс у кількох позиціях, — тож там, де це важливо, відмова через відсутній .wasm, A plugin’s .wasm is not on this machine (Модуля Wasm плагіна немає на цій машині), наводить ім’я повністю. aggrega lint <plugin.yaml> читає .wasm із того самого місця — поруч із переданим їй файлом сутності, у будь-якій директорії, де цей файл лежить, — якщо тільки сам бінарний файл не містить цей плагін, і виводить повідомлення для кожного експорту, можливості чи контракту, про які повідомляє .wasm, але які сутність пропускає. Якщо там немає .wasm, lint повідомляє, що пропустив цей звіт, називаючи файл, який шукав, і директорію, і його результат не змінюється.
Довідку за кожним полем див. на сторінці сутності ../entities/plugin.md.
6. Посилання на плагін
Крок конвеєра або сокет плагіна посилається на плагін за URI сутності Plugin — ідентичністю сутності, а не безпосередньо на артефакт .wasm. Сутність — це шар, що несе закріплений дайджест, заявлені можливості, обмеження виконання та підпис; посилаючись на сутність, споживач отримує все це.
Простий шлях до .wasm або сире посилання на артефакт у полі plugin відхиляється під час завантаження: жодна сутність Plugin йому не відповідає, тож розв’язання плагіна явно завершується помилкою. URI сутності обов’язковий — опосередкування через сутність є контрактом, а не необов’язковою зручністю. Крок конвеєра FeatureRecipe називає сутність у pipeline[].plugin; про поверхню створення конвеєра див. ../entities/featurerecipe.md.
Коли два або більше плагінів пов’язані між собою — вони мають узгоджувати спільний контракт передачі даних, як у парі Fetcher та Injector, де вихід одного плагіна є входом іншого (принцип двочастинного Plugin, описаний у plugin-contract.md), — опишіть цей контракт один раз і зробіть так, щоб кожен плагін залежав від єдиного визначення, а не відтворював форму JSON для передачі даних незалежно в кожному плагіні. Спільна форма — це структура JSON, якою обмінюються плагіни; вона може міститися в одному записі SchemaLibrary, на який посилаються обидва плагіни. Єдине джерело контракту зберігає узгодженість пов’язаних плагінів у міру його розвитку; незалежні відтворення розходяться, і це розходження виявляється лише тоді, коли плагіни вже не узгоджуються під час виконання. Рекомендація полягає в тому, щоб спільним був контракт, а не код Wasm: кожен плагін залишається окремим артефактом.
7. Життєвий цикл: публікація → отримання → збирання
Плагін проходить три етапи, щоб із файлу .wasm на диску стати перевіреним артефактом, придатним для збирання.
Публікація. aggrega push публікує сутність Plugin разом з її .wasm як єдиний OCI-маніфест із тегом metadata.version: YAML сутності є config blob маніфесту, а .wasm іде як шар того самого маніфесту. Саме публікація пари як одного маніфесту з тегом робить push атомарним — немає проміжку часу, коли одну половину опубліковано, а іншу ні, — і саме тому один підпис над цим маніфестом охоплює обидві половини. Обидві половини названо в маніфесті, тож звичайний OCI-клієнт, що отримує тег версії, записує сутність у entity.yaml, а виконуваний файл — у entity.wasm.
Перш ніж буде записано хоч один байт, публікація виконує свої перевірки. Спершу сутність зчитується за схемою Plugin так само, як її зчитує завантаження каталогу, тож metadata.version, що не є семантичною версією, — чи будь-яке інше відхилення від схеми — відхиляється ще до зчитування .wasm. Потім .wasm завантажується, і його самозвіт describe() звіряється із заявленими в сутності можливостями — розбіжність явно зупиняє процес, тож опублікована сутність ніколи не заявляє того, про що не повідомляє плагін, який вона постачає. Гостьовий модуль, версія походження збирання в describe() якого має позначку -dirty, якою позначається збирання з робочого дерева з незакоміченими змінами, відхиляється: ця версія називає коміт, що не містить зібраного. Версія для розробки, зібрана з коміту (1.0.0-3-g1a2b3c4), і попередній випуск (1.0.0-rc.1) публікуються. Записана metadata.version звіряється з версією походження збирання в describe() гостьового модуля, і розбіжність зупиняє публікацію, тож вони мають збігатися. Обидві відмови усуваються однаково: зберіть плагін із чистого checkout коміту, на який указує тег випуску, щоб він повідомляв саму версію випуску, — для нового випуску спершу закомітьте сутність разом із кодом, який вона випускає, і позначте цей коміт тегом. Копіювання в сутність версії, яку повідомляє збирання для розробки, не є виправленням: так це збирання публікується під версією, якої не називає жоден тег випуску. Функції хоста, які імпортує .wasm, виводяться з бінарного файлу й порівнюються із записом, закоміченим у spec.runtime.hostFunctions; розбіжність зупиняє публікацію з посиланням на aggrega plugin sync, яка перезаписує це поле, адже поле належить машині, а публікація ніколи не переписує закомічений файл сутності. Опублікована сутність містить проставлений запис функцій хоста; дайджест вмісту .wasm є властивістю маніфесту, у вигляді якого публікується пара, і для споживача він записується в lockfile сутності Release, а не в сутність.
Отримання. aggrega pull розв’язує всі залежності сутності Release і записує lockfile для кожної сутності Release, що фіксує кожну сутність каталогу й віддалений артефакт за версією та дайджестом вмісту. Опублікована сутність Plugin розв’язується через це розв’язання залежностей; її .wasm завантажується разом із маніфестом, що його містить, а байти перевіряються за дайджестом вмісту, записаним у lockfile. Крім того, отримання повторно виводить функції хоста з перевіреного .wasm і звіряє їх із проставленим записом hostFunctions, зупиняючись у разі розбіжності, — це додаткова захисна перевірка понад фіксацію дайджесту, яка виявляє бінарний файл, позначку якого створено не з його власних імпортів. Якщо політика довіри реєстру вимагає підписів, підпис сутності на цьому етапі завантажується, перевіряється й записується в lockfile як перевірений факт (розділ 8). Перевірка відбувається під час отримання, ніколи під час збирання, — збирання залишається суто AOT (ahead-of-time).
Збирання. aggrega build використовує зафіксований і перевірений плагін із розв’язаних залежностей. Компілятор маршрутизує посилання, зафіксоване за дайджестом, а середовище виконання Wasm виконує байти; перед запуском плагіна шлюз завантаження повторно виконує звіряння describe(), а також застосування обмежень функцій хоста й обмежень середовища виконання.
8. Підписування та довіра
Сутність Plugin підписується так само, як і будь-яка інша сутність каталогу: підписується дайджест маніфесту, і підпис прикріплюється як OCI referrer. Артефакт .wasm не підписується окремо, і окремий підпис йому не потрібен: він є шаром того самого маніфесту, дайджест якого підписано, тож підпис охоплює його безпосередньо: зміна .wasm змінює дайджест маніфесту й робить підпис недійсним.
Підписування під час публікації вмикається за бажанням; перевірку під час pull забезпечує політика довіри окремого реєстру. Реєстр, налаштований вимагати підписи, зупиняє pull, коли обов’язковий підпис відсутній, не є довіреним або недійсний. Блок spec.signature у сутності — це документаційне посилання на те, де зберігається підпис і як його створено; він фіксує факти для читачів каталогу і сам не вирішує, чи допустити сутність. Таким бар’єром є політика, що діє під час pull.
Команди та їхні прапорці задокументовано разом з інтерфейсами публікації та споживання — див. ../cli/aggrega-sign.md, ../cli/aggrega-push.md і ../cli/aggrega-pull.md. Цей посібник не повторює таблиць прапорців; ті сторінки є єдиним місцем опису інтерфейсу команд.
9. Версіонування сутності
Сутність Plugin має строгу семантичну версію в metadata.version. Опублікована версія незмінна: повторну публікацію версії, яка вже існує в реєстрі, з іншим вмістом відхиляє контроль публікації.
Коли ви змінюєте сутність плагіна й публікуєте її повторно, дисципліна публікації класифікує зміну відносно попередньо опублікованої версії та вимагає, щоб підвищення версії їй відповідало. Класифікацію задає рубрика підвищення версії: зміна лише документації або коментарів — це PATCH; строго адитивна зміна (нове необов’язкове поле, новий запис) — MINOR; видалення, звуження типу або перетворення раніше необов’язкового поля на обов’язкове — MAJOR. Надмірне підвищення дозволене завжди; недостатнє підвищення зупиняє роботу з діагностикою, що називає потрібне підвищення. Перша публікація сутності пропускає перевірку підвищення й виводить попередження, що перевірку не виконано. Запустіть перевірку перед публікацією командою aggrega lint --pre-publish; повну рубрику та налаштування окремих правил див. у ../cli/aggrega-lint.md.
Сутність Plugin не має поверхні extends, тож правила успадкування, які діють для сутностей Components і Features каталогу, на неї не поширюються. Рубрика підвищення версії та незмінність — це дисципліна версіонування, яка діє для сутності плагіна.
10. Перехресні посилання
authoring-a-provider-walkthrough.md— повна побудова одного гостьового модуля провайдера, від порожнього каталогу до згенерованого виводу.plugin-contract.md— точки сокетів, на які націлюється плагін, і форми вводу та виводу для кожного сокета.policy-socket.md— докладно про сокет керування: його чотири ролі, рівні серйозності вердиктів, канал вводу оператора, написання політики для будь-якого з двох рушіїв, що постачаються в складі компілятора, і еталонні гостьові модулі політик.core-importers.md— власні імпортери компілятора, по одному для кожного формату, який він читає, побудовані на пакеті імпортерів набору Go: що читає кожен із них, їхні налаштування та їхня публікація з кожним випуском компілятора.../compatibility.md— як версіонуються набори для розробки плагінів і що забезпечує, щоб плагін, зібраний для одного випуску, і далі завантажувався в наступному.../entities/plugin.md— довідник полів сутностіPlugin.../entities/featurerecipe.md— поверхня створенняpipeline:сутності FeatureRecipe, яка посилається на плагін за URI сутності.../cli/aggrega-lint.md— лінтер публікації, критерії підвищення версії та забезпечення незмінності.../cli/aggrega-inspect.md— перегляд можливостей, обмежень середовища виконання та підпису сутностіPlugin.../cli/aggrega-push.md,../cli/aggrega-pull.md,../cli/aggrega-sign.md— команди для публікації, споживання та підписування.