Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Руководство разработчика 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 КиБ на страницу); 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/v1beta1
kind: Plugin
metadata:
name: aws-secrets-manager
version: 1.2.0
pluginType: pipeline-step
spec:
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 в lockfile этой сущности Release, и сборка проверяет по нему загруженные байты: идентичность — в сущности, проверенные байты — в lockfile.
  • 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, где выход одного плагина служит входом другого (принцип двухчастного плагина, Two-Part Plugin Principle, описанный в 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() гостевого модуля, и расхождение прерывает публикацию, поэтому они должны совпадать. Оба отказа устраняются одинаково: соберите плагин из чистой копии коммита, на который указывает тег выпуска, чтобы он сообщал саму версию выпуска, — для нового выпуска сначала зафиксируйте сущность вместе с исходным кодом, который она выпускает, и поставьте тег на этот коммит. Копирование в сущность версии, которую сообщает сборка разработки, не является исправлением: так эта сборка публикуется под версией, которую не называет ни один тег выпуска. Функции хоста, импортируемые .wasm, выводятся из двоичного файла и сравниваются с записью, зафиксированной в spec.runtime.hostFunctions; расхождение прерывает публикацию с указанием на aggrega plugin sync, которая заново записывает это поле, поскольку поле принадлежит машине, а публикация никогда не переписывает зафиксированный файл сущности. Опубликованная сущность несёт проставленную запись функций хоста; дайджест содержимого .wasm является свойством манифеста, в виде которого публикуется пара, и он записывается для потребителя в lock-файл сущности Release, а не в сущность.

Получение. aggrega pull разрешает все зависимости сущности Release и записывает lock-файл для каждой сущности Release, закрепляющий каждую сущность каталога и удалённый артефакт за версией и дайджестом содержимого. Опубликованная сущность Plugin разрешается через это разрешение зависимостей; её .wasm загружается вместе с несущим его манифестом, и байты проверяются по дайджесту содержимого, записанному в lock-файле. Получение также заново выводит функции хоста из проверенного .wasm и сверяет их с проставленной записью hostFunctions, прерываясь при расхождении, — это эшелонированная проверка поверх закрепления по дайджесту, которая выявляет двоичный файл, чья отметка получена не из его собственных импортов. Если политика доверия реестра требует подписей, подпись сущности загружается и проверяется на этом этапе и записывается как проверенный факт в lock-файл (раздел 8). Проверка происходит при получении, а не при сборке — сборка остаётся чистой в смысле 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 — команды публикации, получения и подписи.