Схема сокета импортера 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 | любой | нет | Непрозрачный документ параметров импорта, который потребитель передаёт для поведения, специфичного для импортёра. Хост передаёт его дальше, не интерпретируя; импортёр читает ту структуру, которую он документирует. Отсутствует, если потребитель не передаёт параметров. |
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 | да | Содержимое файла заготовки. |
Дополнительные свойства не допускаются.