Схема сокета імпортера Aggrega Wasm
Згенерований довідник. Не редагуйте вручну — згенеруйте повторно з опублікованої JSON Schema.
Ідентифікатор схеми: https://aggrega.ai/schemas/wasm-import-v1beta1.schema.json
Формати даних, які сокет плагіна-імпортера споживає (ImportInput) і видає (ImportOutput). Імпортер перетворює сторонній опис інфраструктури на сутності Aggrega: він читає вихідні байти для названого формату, зіставляє кожен вузол джерела із сутністю каталогу й повертає видані сутності, ухвалені рішення щодо зіставлення, усі діагностичні повідомлення, які він згенерував, і всі створені ним файли-заготовки. Імпортер оголошує формати, які він обробляє, як можливості import:
Одна з наведених нижче форм
ImportInputImportOutput
Визначення
ImportInput
Корисне навантаження, яке отримує гостьовий модуль імпортера: вихідний формат, що визначає, як читати байти, основні вихідні байти та ім’я файлу, з якого їх прочитано, будь-які іменовані джерела для багатофайлового імпорту, необов’язковий непрозорий документ параметрів, який споживач надає для специфічної для імпортера поведінки, подання сутностей Components, що містить каталог робочого простору, і ціль, для якої імпорт створює чернетки.
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
format | string | так | Назва вихідного формату для імпорту, що відповідає одній із заявлених імпортером можливостей import: |
bytes | string | так | Основні вихідні байти для імпорту, які імпортер читає в зазначеному форматі: увесь файл, якщо джерело імпорту — один файл, і порожні, якщо це каталог, файли якого натомість надходять як іменовані джерела. Кожен набір інструментів передає їх у власному типі поля — у сирому вигляді, якщо цей тип є байтовим, і в кодуванні base64, якщо це рядок, який імпортер декодує, щоб відновити їх, — а згенерований кодувальник перетворює дані між полем і формою, у якій байти передаються по каналу. |
name | string | ні | Ім’я джерела імпорту без каталогу перед ним, щоб імпортер міг назвати джерело в тому, що він повідомляє, і в тому, що він створює як чернетку. Коли джерелом є один файл, це базове ім’я файлу: основні байти надходять не як іменоване джерело, тож це єдине ім’я, яке вони мають. Коли джерелом є каталог, це базове ім’я каталогу, а файли каталогу й далі надходять як іменовані джерела, кожен під власним іменем, з порожніми основними байтами. Відсутнє, коли джерело не має імені, яке можна передати. |
sources | ImportSource[] | ні | Іменовані джерела, кожне з власними байтами, в одному списку, відсортованому за назвою. Якщо джерело імпорту — каталог, є по одному джерелу на кожен його файл, який вибирають оголошені шаблони файлів імпортера, з назвою за шляхом усередині каталогу, розділеним скісними рисками. Файли, які приєднання, що налаштовує імпортер, оголошує в with.sources, також передаються тут, кожен під своєю базовою назвою, і хост відхиляє імпорт, у якому файл, прочитаний із каталогу, і один із цих файлів мають однакову назву. Відсутнє, якщо жодне з них нічого не надає. |
settings | any | ні | Непрозорий документ параметрів імпорту, який споживач надає для специфічної для імпортера поведінки. Хост передає його далі, не інтерпретуючи; імпортер читає ту структуру, яку сам документує. Відсутнє, якщо споживач не надає параметрів. |
catalog | CatalogProjection | ні | Подання сутностей Components, що містить власний каталог робочого простору — каталог, з якого вибрано сам імпортер, — щоб імпортер міг зважувати їх як кандидатів, коли зіставляє вихідний вузол із сутністю каталогу. Хост будує його лише з цього локального каталогу, і воно містить лише назви, версії, мітки й оголошену структуру: ніколи не значення, не типове значення й не секрет. Його порядок фіксований, тож один каталог дає одну послідовність байтів. Відсутнє, якщо каталог не містить жодної сутності Component. |
target | string | ні | Можливість провайдера, для якої імпорт створює чернетки, наприклад compose або helm: ціль, передана імпорту, або, для імпорту, що оновлює попередній і сам не називає жодної цілі, ціль, яку записав той попередній імпорт. Імпортер записує в чернетки як оголошення те, що потрібно лише цій цілі, і пропускає те, що потрібно лише іншій цілі. Хост передає її без змін, після того як перевірить, що сутність Recipe з каталогу робочого простору прив’язується до неї. Відсутнє, якщо імпорт не називає жодної цілі. |
Додаткові властивості не дозволені.
CatalogProjection
Каталог робочого простору таким, яким його бачить імпортер: по одному запису на кожну сутність Component, що містить каталог, кожен із метаданими, які імпортер зважує, коли оцінює кандидата.
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
components | CatalogComponent[] | так | По одному запису на кожну назву сутності Component, що містить каталог, відсортовано за назвою. Якщо каталог містить кілька версій однієї сутності Component, її запис описує версію, до якої розв’язується посилання, що називає цю сутність Component без версії. |
Додаткові властивості не дозволені.
CatalogComponent
Одна сутність Component каталогу робочого простору: її назва й версія, її мітки, назви ключів, які оголошують її values і provides, і сокети, які вона оголошує для своїх залежностей. Сутність Component, що розширює іншу, містить і те, що успадковує, і те, що оголошує сама.
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
name | string | так | Назва сутності Component, як її оголошує metadata.name, — назва, за якою на неї посилається сутність Aggregate. |
version | string | так | Версія сутності Component, як її оголошує metadata.version. |
labels | map of string | ні | Мітки сутності Component у вигляді відображення рядків на рядки. Відсутнє, якщо міток немає. |
values | string[] | ні | Назви ключів верхнього рівня, які оголошують values сутності Component, відсортовані. Лише список назв: ніколи не містить значення чи типового значення. Відсутнє, якщо її values не оголошує жодного ключа. |
provides | string[] | ні | Назви ключів верхнього рівня, які оголошують provides сутності Component, відсортовані. Лише список назв: ніколи не містить значення. Відсутнє, якщо її provides не оголошує жодного ключа. |
sockets | CatalogSocket[] | ні | Сокети, які сутність Component оголошує для своїх залежностей, у порядку оголошення: для сутності Component, що розширює іншу, спершу йдуть успадковані сокети в порядку, у якому їх оголошує розширювана сутність Component, а за ними — додані. Відсутнє, якщо сокетів не оголошено. |
Додаткові властивості не дозволені.
CatalogSocket
Один сокет, який сутність Component каталогу оголошує для своїх залежностей: назва сокета й селектор міток, якому має відповідати залежність, під’єднана через нього.
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
name | string | так | Назва сокета, як її оголошує usesSchema сутності Component. |
selector | string | так | Селектор міток сокета дослівно, у граматиці в стилі Kubernetes, якою його записує сутність Component: мітки, які має мати залежність, під’єднана через цей сокет. |
Додаткові властивості не дозволені.
ImportSource
Одне іменоване джерело в межах багатофайлового імпорту або імпорту каталогу: назва, що вказує на джерело, і його власні байти.
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
name | string | так | Назва цього джерела в межах імпорту, наприклад відносний шлях до файлу. |
bytes | string | так | Байти цього джерела. Кожен набір інструментів передає їх у власному типі поля — у сирому вигляді, якщо цей тип є байтовим, і в кодуванні base64, якщо це рядок, який імпортер декодує, щоб відновити їх, — а згенерований кодувальник перетворює дані між полем і формою, у якій байти передаються по каналу. |
Додаткові властивості не дозволені.
ImportOutput
Корисне навантаження, яке повертає гостьовий модуль імпортера: сутності, створені імпортом, рішення про зіставлення, що стоять за ними, будь-яка діагностика, виявлена імпортом, і будь-які створені ним файли заготовок. Кожне поле необов’язкове, тож імпорт, який нічого не розв’язав, може повернути лише діагностику.
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
entities | EmittedEntity[] | ні | Сутності, створені імпортом, кожна з яких є або посиланням на наявну сутність каталогу, або чернеткою тіла сутності. Відсутнє, якщо імпорт не видав жодної сутності. |
decisions | ImportDecision[] | ні | Рішення про зіставлення, ухвалені імпортом, по одному на кожен розв’язаний вихідний вузол, із записом зважених кандидатів і зробленого вибору. Відсутнє, якщо імпорт не записав жодного рішення. |
diagnostics | Diagnostic[] | ні | Діагностика, виявлена імпортом, — наприклад, нерозв’язаний вихідний вузол або неоднозначне зіставлення. Відсутнє, якщо імпорт нічого не видав. |
files | ScaffoldFile[] | ні | Файли заготовок, створені імпортом разом із сутностями, наприклад початковий aggregate або readme. Відсутнє, якщо імпорт не створив файлів. |
error | string | ні | Повідомлення про збій, що задається, коли гостьовий модуль виконався, але не зміг завершити операцію; відсутнє в разі успіху. Воно відрізняється від будь-якої діагностики у виводі: діагностика повідомляє про проблеми, виявлені під час виконання, яке все ж дало результат, тоді як error повідомляє, що сама операція не завершилася. Наявну помилку хост показує як невдалий виклик плагіна. |
Додаткові властивості не дозволені.
EmittedEntity
Одна сутність, створена імпортом: її вид, її назва і спосіб видачі — посилання на наявну сутність каталогу або нова чернетка тіла сутності.
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
kind | string | так | Вид виданої сутності. Базові імпортери видають Component, Aggregate і Release; читач має допускати будь-який інший вид. |
name | string | так | Назва виданої сутності. |
mode | string (enum) | так | Спосіб видачі сутності: reference вказує на наявну сутність каталогу за назвою, а draft містить нову чернетку тіла сутності. Дозволені значення: "reference", "draft" |
body | string | ні | Сире тіло YAML чернетки сутності. Порожнє для чистого посилання, яке називає наявну сутність, а не створює чернетку. |
labels | map of string | ні | Мітки, які слід приєднати до виданої сутності, у вигляді відображення рядків на рядки. Базові імпортери залишають його порожнім. |
annotations | map of string | ні | Анотації, які слід приєднати до виданої сутності, у вигляді відображення рядків на рядки. Базові імпортери залишають його порожнім. |
sourceRef | string | ні | Посилання на вихідний вузол, з якого видано цю сутність, щоб читач міг простежити сутність до її походження в імпортованому джерелі. |
decisionRef | string | ні | Посилання на рішення про зіставлення, яке створило цю сутність, що пов’язує її зі зваженими кандидатами й зробленим вибором. |
Додаткові властивості не дозволені.
ImportDecision
Одне рішення зіставлення: вузол джерела, який розв’язав імпортер, кандидати серед сутностей каталогу, які він зважив, кандидат, якого він обрав, і обґрунтування цього вибору.
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
sourceNode | DecisionSourceNode | так | Вузол джерела, який розв’язало це рішення: вузол, який імпортер прочитав із джерела та зіставив із сутністю каталогу. |
candidates | ImportCandidate[] | ні | Кандидати серед сутностей каталогу, які імпортер зважив для цього вузла джерела, кожен зі своєю оцінкою та розбивкою за сигналами, що лежить в основі цієї оцінки. Відсутнє, коли імпортер не зважував жодних кандидатів. |
chosen | DecisionChoice | ні | Кандидат, якого імпортер обрав для цього вузла джерела, і спосіб, у який він його видав. Відсутнє, коли імпортер не зробив вибору. |
rationale | string | ні | Зрозуміле людині пояснення того, чому імпортер зробив цей вибір. |
swapHint | string | ні | Підказка, що описує, як замінити обране зіставлення альтернативним, щоб читач міг переглянути рішення. |
Додаткові властивості не дозволені.
DecisionSourceNode
Вузол джерела, який розв’язало рішення зіставлення: ідентифікатор, тип, яким його називає джерело, і зрозумілий людині підсумок його параметрів.
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
id | string | так | Ідентифікатор вузла джерела в межах імпортованого джерела. |
type | string | так | Тип вузла джерела так, як його називає джерело. |
paramsSummary | string | так | Зрозумілий людині підсумок параметрів вузла джерела для показу поряд із рішенням. |
Додаткові властивості не дозволені.
ImportCandidate
Один кандидат серед сутностей каталогу, якого імпортер зважив для вузла джерела: компонент-кандидат, його загальна оцінка, рівень відповідності, до якого належить оцінка, і розбивка за сигналами, що лежить в основі оцінки.
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
componentName | string | так | Назва компонента каталогу, що є кандидатом. |
score | number | так | Загальна оцінка відповідності кандидата, агрегована з розбивки за сигналами. |
tier | string | так | Рівень відповідності, до якого належить кандидат, — грубий діапазон поверх оцінки. |
signals | CandidateSignals | так | Розбивка за сигналами, що лежить в основі оцінки кандидата. |
Додаткові властивості не дозволені.
CandidateSignals
Розбивка за сигналами, що лежить в основі оцінки кандидата: один внесок на кожен сигнал відповідності. Це об’єкт із фіксованими полями, тож набір сигналів стабільний, а дані в каналі детерміновані.
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
table | number | так | Внесок в оцінку від сигналу таблиці зіставлень. |
category | number | так | Внесок в оцінку від сигналу категорії. |
domainLabels | number | так | Внесок в оцінку від сигналу доменних міток. |
shape | number | так | Внесок в оцінку від сигналу форми. |
name | number | так | Внесок в оцінку від сигналу назви. |
Додаткові властивості не дозволені.
DecisionChoice
Кандидат, якого обрало рішення зіставлення: цільова сутність каталогу, спосіб її видачі та рівень відповідності вибору.
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
target | string | так | Назва обраної цільової сутності каталогу. |
mode | string | так | Спосіб видачі обраної цілі, що відповідає режиму виданої сутності: посилання на наявну сутність або щойно створене чернеткове тіло. |
tier | string | так | Рівень відповідності обраної цілі. |
Додаткові властивості не дозволені.
ScaffoldFile
Один файл-заготовка, створений імпортом: шлях відносно кореня виводу імпорту та вміст файлу.
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
path | string | так | Шлях файлу-заготовки відносно кореня виводу імпорту. |
content | string | так | Вміст файлу-заготовки. |
Додаткові властивості не дозволені.