Plugin
Plugin — это плагин WebAssembly с адресацией по содержимому: размещённый в OCI артефакт .wasm, закреплённый по дайджесту sha256, который объявляет реализуемый им тип сокета, целевую версию ABI, необязательный указатель на подпись и необязательный блок runtime. Эта сущность — поверхность авторинга и метаданных для плагина; разрешение зависимостей закрепляет артефакт по дайджесту, а политика доверия каждого реестра проверяет его подпись при загрузке. Компилятор не интерпретирует поведение плагина — он передаёт закреплённую ссылку; байты исполняет среда выполнения WebAssembly.
На этой странице поле за полем описана поверхность авторинга каталога Plugin. Сквозной рабочий процесс автора — что такое плагин, самоотчёт describe(), жизненный цикл publish→pull→build, подписание и версионирование — описан в руководстве разработчика плагинов 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/v1beta1kind: Pluginmetadata: name: aws-secrets-manager version: 1.2.0 pluginType: pipeline-stepspec: 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 credentialmetadata
Стандартные метаданные каталога. 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 | Где объявляются его возможности | Что называет запись |
|---|---|---|
provider | spec.provider.capabilities | Возможность рендеринга, которую обслуживает этот плагин, например helm или compose. |
pipeline-step | spec.pipelineStep.capabilities | Провайдер, с отрендеренным выводом которого совместим шаг этого плагина. |
parser | spec.parser.capabilities | Исходный формат, который читает этот плагин, в записи parse:<format>. |
importer | spec.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
Блок сокета провайдера для плагина pluginType: provider: возможности, которые он обслуживает, то, как он транслирует принадлежащий платформе вид Workload aggrega.ai/v1beta1, какие нативные для платформы аннотации он читает, и его контракт поведения рендеринга. Блок присутствует у каждого плагина, выполняющего рендеринг провайдера, и отсутствует у плагинов всех остальных типов. Провайдер, который рендерит только исходное содержимое или содержимое артефактов без синтеза Workload, всё равно содержит этот блок: он объявляет в нём свои возможности и свой контракт и просто опускает workloadSchema.
spec.provider.capabilities
Возможности, которые обслуживает этот провайдер, — имена возможностей, такие как helm или compose, — форму вывода которых он рендерит. Провайдер универсален в пределах артефактов, разделяющих форму вывода одной возможности, а не в пределах всех возможностей, поэтому список называет возможности, о которых сообщает сам плагин: aggrega plugin gen-catalog записывает его из describe() плагина, и автор может сузить его перед публикацией. Записи сохраняют порядок, в котором они записаны.
Запрошенная в сущности Recipe цель провайдера (spec.capability: helm) разрешается в плагин провайдера, список которого содержит эту цель. Если одну и ту же цель перечисляют несколько плагинов провайдеров, выбор делает рабочее пространство: выбор plugins.providers в конфигурации рабочего пространства указывает, какой плагин использовать; он разрешается при aggrega pull и записывается в lock-файл. Если выбора нет и кандидат ровно один, используется этот кандидат; если выбора нет и кандидатов несколько, сборка останавливается и называет всех кандидатов. Неоднозначность разрешается для каждого рабочего пространства в месте использования, а не правилом уникальности на уровне всего каталога. Пустой или отсутствующий список не объявляет никаких возможностей, поэтому плагин не обслуживает ни одной цели.
Имя возможности здесь не содержит двоеточия. Поле spec.capability сущности Recipe читается как возможность до последнего двоеточия и закрепление версии после него, поэтому имя, содержащее двоеточие, никогда не удалось бы запросить; плагин, чей describe() сообщает такое имя, отклоняется при загрузке, и из него не генерируется ни одна сущность для публикации. То же относится к возможностям провайдеров, которые перечисляет плагин pipeline-step. Двоеточие в parse:<format> парсера и import:<format> импортера является частью этих имён и сохраняется.
spec.provider.workloadSchema
Объявление JSON Schema 2020-12, документирующее, как этот провайдер транслирует вид Workload aggrega.ai/v1beta1 в нативные для провайдера манифесты. Оно объявляется по соглашению у провайдера, выполняющего синтез: такой провайдер объявляет workloadSchema как документированный контракт трансляции, описывающий, какие поля Workload потребляет провайдер, какие закрытые множества принимает каждое поле в форме перечисления и какие ограничения диапазона действуют.
Тело компилируется в JSON Schema 2020-12 при загрузке сущности Plugin — это структурная защита, отклоняющая некорректную схему при загрузке, а не при рендеринге. Поддерживается ли Recipe с workload:, определяется способностью привязанного провайдера к синтезу, а не наличием этого поля: Recipe в синтезируемом режиме, привязанный к провайдеру, который не умеет синтезировать, явно останавливается во время рендеринга. Каталог стандартной библиотеки поддерживает workloadSchema в соответствии с возможностями провайдера. Поле является документированным контрактом; больше его ничто не читает. Сами тела Workload проверяются по принадлежащей платформе встроенной схеме Workload, а не по этому полю отдельного провайдера.
spec.provider.wellKnownAnnotations
Упорядоченный массив, перечисляющий нативные для платформы общеизвестные ключи аннотаций — находящиеся в зарезервированном пространстве имён aggrega.ai/, — которые читает этот провайдер, вместе с поведением, применяемым при отсутствии каждого из них. Каждая запись содержит key (аннотация, читаемая провайдером, например aggrega.ai/namespace), purpose (что аннотация определяет, если присутствует), необязательное defaultBehavior (что делает провайдер, если аннотация отсутствует) и необязательное scope, перечисляющее, где провайдер читает ключ, — sourced, synthesized или artifactsStandalone, виды входных данных Recipe, или boundary для ключа, читаемого один раз на границу. key и purpose обязательны; записи сохраняют порядок, заданный автором.
Поле является заявлением провайдера о поддержке, и компилятор читает его двумя способами. Запись, чьё scope называет вид входных данных, который не заявлен в собственном contract.inputKinds блока, противоречит этому заявлению, и Plugin отклоняется с указанием ключа и области. Кроме того, когда сборка выполняет рендеринг через этого провайдера, аннотация aggrega.ai/, которую ни одна запись не покрывает ни для одного вида входных данных, объявленного рендерингом, вызывает предупреждение с указанием ключа, провайдера и этих видов входных данных; значение по-прежнему передаётся без изменений, и сборка не останавливается. При отсутствии поле ничего не заявляет, и для этого провайдера такое предупреждение не выдаётся. Проверка схемы проверяет только форму каждой записи (ключ находится в пространстве имён aggrega.ai/, purpose присутствует); она отличается от проверки во время выполнения, которая регулирует привязку значения к зарезервированному пространству имён.
metadata: pluginType: providerspec: 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.Наборы аннотаций отдельных провайдеров и содержимое workloadSchema, поставляемые провайдерами стандартной библиотеки, описаны в ../providers/well-known-annotations.md, ../providers/helm.md, ../providers/helm-chart.md и ../providers/compose.md.
spec.provider.readsNoWellKnownAnnotations
Объявляет, что этот провайдер не читает ни одного из нативных для платформы общеизвестных ключей аннотаций. Это заявление о поддержке, не покрывающее ни одного ключа, и оно говорит то, чего не говорит отсутствие и его, и wellKnownAnnotations: отсутствующее заявление — это молчание, а это — собственное утверждение провайдера о том, что он ничего не читает в зарезервированном пространстве имён aggrega.ai/. Сборка, выполняющая рендеринг через такого провайдера, предупреждает о каждой аннотации aggrega.ai/, достигающей рендеринга, с указанием ключа, провайдера и видов входных данных, объявленных рендерингом; значение по-прежнему передаётся без изменений, и сборка не останавливается.
Можно записать только true, поэтому пропуск поля остаётся единственным способом ничего не заявлять. Его нельзя записать вместе с wellKnownAnnotations: провайдер, читающий некоторые из ключей, вместо этого перечисляет их там. Оба отказа выполняются на уровне схемы, поэтому Plugin отклоняется при чтении.
spec: provider: capabilities: - terraform readsNoWellKnownAnnotations: trueЕго объявляет провайдер terraform из стандартной библиотеки; ../providers/terraform.md объясняет, что это означает для сущности Release, отрендеренной через него.
spec.provider.contract
Самостоятельно объявленный контракт поведения рендеринга во время компиляции для плагина, выполняющего рендеринг провайдера: какие виды входных данных он рендерит, как собирает вывод отдельных узлов группы диспетчеризации, какую пару разделителей шаблонов применяет к импортированным файлам артефактов, может ли один загруженный экземпляр обслуживать все пересечения, учитывает ли он записи исключения и принимает ли файлы, которые 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 | Учитывает ли плагин записи исключения — записи, называющие отрендеренные единицы, которые нужно исключить из вывода узла: он исключает из рендеринга каждую единицу, совпавшую с записью, и сообщает, со сколькими единицами совпала каждая запись. Значение фиксирует заявление, которое сообщает describe() плагина, поэтому true верно только для плагина, который это сообщает, а значение, отличающееся от отчёта, останавливает сборку. Отсутствие (false) означает, что такая поддержка не объявлена. |
boundaryArtifacts | Принимает ли цель плагина файлы, которые Recipe добавляет в общий вывод границы, в которой он рендерит, согласно spec.boundary.artifacts сущности Recipe: компилятор записывает каждый такой файл один раз рядом с тем, что плагин собирает для границы, и цель читает его как часть этого вывода. Значение фиксирует заявление, которое сообщает describe() плагина, а значение, отличающееся от отчёта, останавливает сборку. Отсутствие (false) означает, что такая поддержка не объявлена, и сущность Recipe, объявляющая этот блок для данного плагина, отклоняется до начала рендеринга. |
metadata: pluginType: providerspec: 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: truespec.pipelineStep
Блок шага конвейера для плагина с pluginType: pipeline-step. Его единственное поле, capabilities, называет провайдеры, отрендеренный вывод которых шаг плагина умеет преобразовывать, — имена возможностей, такие как helm или compose. Шаг пишется в расчёте на форму вывода одного провайдера за раз, поэтому список называет провайдеры, о которых сообщает сам плагин; записи сохраняют порядок, в котором они записаны. Блок присутствует только у плагинов шагов конвейера.
Блок — это доступная для чтения каталогом запись этого заявления: aggrega plugin gen-catalog записывает его из собственного самоотчёта плагина describe(), и автор может сузить его перед публикацией. Проверка считывает то же заявление из плагина: когда шаг затрагивает область, сборка останавливается, если провайдер, рендерящий документы этой области, не входит в число заявленных плагином. Пустой или отсутствующий список не объявляет никакой совместимости, поэтому ни одна область не допускает этот шаг.
metadata: pluginType: pipeline-stepspec: abiVersion: v1beta1 pipelineStep: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - helm - composespec.parser
Блок parser для плагина с pluginType: parser. Его единственное поле, capabilities, перечисляет исходные форматы, которые плагин превращает в каноническое структурированное дерево; каждый записывается как parse:<format>. Префикс входит в запись, поэтому плагин, читающий несколько форматов, указывает по одной записи на каждый формат. aggrega plugin gen-catalog записывает список из собственного describe() плагина, автор может сузить его перед публикацией, а записи сохраняют порядок, в котором они записаны. Блок присутствует только у плагинов-парсеров.
Запрошенный формат разрешается в тот парсер, список которого содержит соответствующую запись. Формат, который не объявляет ни один парсер, останавливает сборку, а формат, объявленный более чем одним плагином-парсером, останавливает её как неоднозначный с указанием кандидатов — запасного варианта нет, поскольку у парсера нет варианта по умолчанию без настройки, к которому можно было бы вернуться. Пустой или отсутствующий список не объявляет никаких форматов, поэтому плагин ничего не разбирает.
metadata: pluginType: parserspec: abiVersion: v1beta1 parser: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - parse:hcl - parse:tomlspec.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: importerspec: abiVersion: v1beta1 importer: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - import:langflow detect: - syntax: json match: - path: data.nodes is: arrayspec.signature
Необязательный описательный указатель на подпись, прикреплённую к плагину. Блок служит только документацией: он фиксирует для читателей каталога, где находится подпись и как она была создана; сам по себе он не допускает плагин. Обязательная проверка — это политика доверия отдельного реестра, применяемая при pull: подпись извлекается как OCI referrer, проверяется по доверенным идентичностям реестра или закреплённому ключу и записывается в lockfile как проверенный факт. Реестр, требующий подписей, останавливает pull, если требуемая подпись отсутствует, не является доверенной или недействительна.
type— схема подписи. Поддерживаемая схема —sigstore-cosign. Обязательно, если блок присутствует.signatureRef— ссылка OCI referrer на прикреплённый пакет подписи, для документации и обнаружения. Отсутствует, если подпись обнаруживается перечислением referrer при pull, а не закрепляется здесь.publicKeyRef— указатель на открытый ключ, которым была создана подпись, для подписи с ключом. Отсутствие означает бесключевую подпись (на основе OIDC-идентичности), проверяемую по доверенным идентичностям реестра.
spec.runtime
Необязательные ограничения выполнения, которые хост применяет при загрузке и запуске плагина. Исходящий сетевой доступ не является авторским полем: плагин никогда не обращается к сети во время сборки — это граница ahead-of-time, — поэтому здесь нет поля со списком разрешённых хостов. Удалённое содержимое, необходимое плагину, поступает через опосредованный хостом, закреплённый по дайджесту канал внешних входных данных, записанный в lock-файле сущности Release, и никогда через неявный сетевой доступ; руководство разработчика описывает обёртку для загрузки и дисциплину закрепления.
| Поле | Действие |
|---|---|
maxMemoryPages | Ограничивает линейную память плагина в страницах Wasm (64 КиБ на страницу). Ноль или отсутствие значения применяет ограничение платформы по умолчанию, поэтому загрузка никогда не бывает неограниченной; подключение, которому нужно больше, увеличивает это значение. |
timeoutMs | Ограничивает время, в течение которого собственный код плагина может выполняться за один вызов, в миллисекундах, не считая времени, проведённого внутри вызываемых им функций хоста. В Linux измеряется процессорное время, поэтому время ожидания процессора на загруженной машине не учитывается; в других системах измеряется реальное прошедшее время. Первый вызов только что загруженного плагина учитывает также собственный запуск плагина. Ноль или отсутствие значения применяет ограничение платформы по умолчанию, поэтому вызов никогда не становится неотменяемым; подключение, которое выполняется дольше, увеличивает это значение. |
hostFunctions | Имена функций хоста, которые импортирует плагин. Выводится автоматически и доступно только для чтения — не задавайте его вручную: aggrega plugin sync считывает функции хоста из секции импорта .wasm и записывает это поле, публикация отклоняет запись, отличающуюся от двоичного файла, а значение отражает опубликованный двоичный файл и проверяется по курируемому списку разрешённых. Хост регистрирует ровно этот набор, предоставляя каждому плагину минимально необходимую поверхность хоста, которая нужна его двоичному файлу; при загрузке из реестра (pull) значение выводится заново и сверяется с двоичным файлом. Чтобы просмотреть значение до публикации, выполните aggrega inspect --plugin <file.wasm>. |
configKV | Plugin-специфичная конфигурация, которую среда выполнения передаёт плагину при запуске, в виде пар ключ/значение «строка — строка». Записи сохраняют авторский порядок, поэтому выводимая запись побайтово идентична между запусками. Если поле отсутствует, действует пустая конфигурация среды выполнения по умолчанию. |
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: clispec: 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.