Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Guía para desarrolladores de plugins Wasm

Esta es la guía canónica para crear un plugin WebAssembly (Wasm) de Aggrega y publicarlo como entidad del catálogo. Enseña el contrato del autor de plugins de principio a fin: qué es un plugin, cómo se describe un plugin ante el host, cómo crear sus exports y sus declaraciones de capacidades, los límites de ejecución y las funciones host que aplica el host, la entidad Plugin que lleva un plugin al catálogo, cómo una Recipe o una FeatureRecipe hace referencia a un plugin, y el ciclo de vida publish→pull→build que lleva un plugin desde un archivo .wasm en disco hasta un artefacto verificado y fijado por digest que consume una compilación.

La página complementaria plugin-contract.md documenta los sockets — los puntos del pipeline donde se vinculan los plugins y las formas de entrada/salida que cada socket consume y produce. Esta guía documenta el plugin — la entidad, la superficie de capacidades y el ciclo de vida. Lee la página del contrato para saber a qué socket se dirige tu plugin; lee esta página para saber cómo crearlo y distribuirlo.

Para un recorrido práctico por toda la tarea en lugar de una referencia sobre ella, crear un proveedor construye de principio a fin un pequeño guest de proveedor — descriptor, compilación, entidad, vinculación y un renderizado cuya salida puedes leer — incluido el rechazo con el que suele encontrarse un primer borrador y cómo leerlo.

1. Qué es un plugin Wasm

Un plugin Wasm es un módulo WebAssembly que amplía el compilador en un socket designado. El binario host de Go no contiene ninguna lógica específica de la nube ni de la infraestructura; toda la inteligencia específica del dominio — renderizado de plantillas, traducción de formatos, evaluación de políticas, linting — reside en los plugins. El host orquesta el pipeline y pasa la carga útil de cada socket al guest a través del límite de la ABI; el guest hace el trabajo de dominio y devuelve la forma de resultado de ese socket. La carga útil y el resultado de cada socket viajan como CBOR canónico, con dos excepciones: un plugin CLI recibe su vector de argumentos como texto JSON y responde con un código de salida y el texto que transmite, y el autoinforme describe es texto JSON. La sección de cada socket en el contrato de los plugins indica su codificación, y un guest la lee y la escribe a través de los puntos de entrada que ya incluye el tipo de carga útil de su kit, así que ningún guest analiza bytes a mano.

Un plugin se ejecuta detrás de un cortafuegos de pureza ahead-of-time. El host carga y ejecuta el módulo mediante un runtime Wasm integrado con una configuración de capacidades denegadas: sin sockets de red, sin sistema de archivos, sin entorno, stdio descartado y un reloj de pared observable congelado en un instante invariante entre compilaciones. Cualquier llamada de E/S que intente un guest falla en el límite de la llamada, así que un plugin no puede recurrir al estado de tiempo de ejecución. Crea los plugins teniendo en cuenta este cortafuegos: un plugin transforma la carga útil que recibe y devuelve un resultado que el host consume tal cual, y el determinismo es responsabilidad tuya — una entrada idéntica debe producir bytes de salida idénticos. El único canal sancionado para el contenido remoto es la obtención de entradas externas mediada por el host (sección 4), que sirve bytes bajo una disciplina de fijación por digest en lugar de dar al guest acceso directo a la red.

Los sockets a los que puede dirigirse un plugin — entre ellos el punto de control de mutación en la construcción de la topología, el punto de control de validación en el análisis estático, el pipeline de FeatureRecipe, el linter fuera de banda y el socket de renderizado de proveedores — y sus formas de entrada/salida por socket se documentan en plugin-contract.md. El socket al que sirve un plugin es el único valor que declara en metadata.pluginType, y el conjunto completo de valores que acepta ese campo es su entrada de referencia en entities/plugin.md §«metadata.pluginType». Los ejemplos de esta guía usan provider (renderiza nodos IR en artefactos nativos del proveedor), linter (inspecciona el contenido creado por el autor y genera diagnósticos) y pipeline-step (un paso en el pipeline: de una FeatureRecipe o de una Recipe que aplica parches al conjunto de documentos renderizados).

Creas el guest frente al host con el kit de desarrollo de plugins (PDK) en tres lenguajes — Go, Rust o TypeScript. El PDK envuelve la cadena de herramientas Wasm subyacente con constructores tipados de Aggrega para las formas de entrada y salida que transporta cada socket.

2. El autoinforme describe()

Cada plugin exporta una función describe() que devuelve el autoinforme del plugin: el tipo o los tipos de socket que implementa, la versión de la ABI a la que se dirige, las capacidades que declara — leídas según el tipo de socket, así que nombres de capacidades para un proveedor o un paso de pipeline y formatos de fuente con prefijo para un analizador o un importador —, las funciones host que importa y la capacidad por export de cada punto de entrada que ofrece. describe() es el relato que el propio plugin hace de lo que es y de lo que hace.

El autoinforme es el ancla del modelo de confianza. La entidad Plugin que lleva el plugin al catálogo (sección 5) reformula los mismos hechos como declaraciones escritas por el autor, y el host contrasta las declaraciones de la entidad con la salida de describe() del plugin en dos momentos — en la publicación, antes de que ningún byte llegue al registro, y en la carga, antes de que se ejecute el plugin. Una discrepancia provoca una detención manifiesta. La entidad es la superficie legible por personas y visible en el catálogo; describe() es la referencia de máquina contra la que el host la verifica. Crea ambas para que coincidan; la verificación cruzada existe precisamente para detectar el caso en que divergen. Comprueba lo que la entidad declara y no lo que omite: una entidad que declara menos de lo que informa el binario — por ejemplo, una que quedó atrás tras una recompilación que añadió un export — sigue cargándose, aunque ya no describa todo lo que hace el binario.

3. Crear los exports y sus declaraciones de capacidades

Un plugin ofrece uno o varios exports — puntos de entrada con nombre a los que el host despacha las llamadas (por ejemplo render_node, lint_naming, step). Cada export lleva un bloque de capacidad: la declaración del autor sobre lo que hace ese export. La capacidad de un export tiene cuatro campos:

  • name — el nombre ABI del export, el nombre al que el host despacha las llamadas. Obligatorio.
  • operates — la operación de pipeline que realiza el export: patch (modificar un documento renderizado existente) o emit (añadir un documento nuevo). Es una declaración de capacidad explícita. El host la contrasta con el autoinforme describe() del plugin en la publicación y en la carga, así que la declaración escrita en la entidad y el relato propio del plugin deben coincidir. Es una declaración validada sobre el export, no un conmutador de despacho: en el momento del renderizado, la operación que un paso realiza realmente la lleva el resultado devuelto por el guest, no se selecciona a partir de este campo. Si está ausente, no lleva ninguna declaración de operación.
  • scope — la raíz de documentos sobre la que opera el export: own (los documentos renderizados propios del nodo) o host (los documentos del componente al que está vinculada una FeatureRecipe con ámbito de componente). Antes de que se ejecute el plugin de un paso de pipeline, el host lee el ámbito de export declarado del paso y exige que el proveedor que renderiza los documentos de ese ámbito aparezca en las spec.pipelineStep.capabilities del plugin (sección 5) — un export con ámbito own se comprueba contra el proveedor que renderiza los documentos propios del nodo, un export con ámbito host contra el proveedor del componente anfitrión, y un ámbito vacío equivale a own para esta comprobación. Este es el punto de control de compatibilidad de proveedores, que se ejecuta antes del paso; el documento que toca realmente una operación del guest se nombra por operación en el resultado devuelto por el guest, no se selecciona a partir de este campo declarado. Si está ausente, el valor predeterminado es own.
  • selector — una descripción libre y legible por personas de aquello sobre lo que actúa el export (por ejemplo workloads carrying a pod template). Documentación para los lectores del catálogo y para la superficie aggrega inspect; el compilador no la interpreta.

Crea los exports en el orden en que quieres que se lean; las entradas conservan el orden del autor en la entidad y en inspect. Un plugin sin exports creados no declara ninguna superficie de export — algo válido para un plugin cuyo socket no necesita una declaración de capacidad por export.

4. Límites de ejecución y funciones host

Una entidad de plugin puede llevar un bloque runtime opcional que restringe cómo el host carga y ejecuta el plugin.

Límites de memoria y de tiempo. maxMemoryPages limita la memoria lineal del plugin en páginas Wasm (64 KiB por página); timeoutMs limita cuánto tiempo puede ejecutarse el código propio del plugin durante una llamada, en milisegundos. El tiempo que se pasa dentro de las funciones host que llama el plugin no cuenta para ese límite. En Linux, la medida es el tiempo de procesador del hilo que ejecuta el guest, así que tampoco cuenta el tiempo que el guest pasa esperando un procesador en una máquina ocupada; en otros sistemas es el tiempo transcurrido. La primera llamada a un plugin recién cargado también cuenta la inicialización única del runtime del lenguaje guest, que se ejecuta dentro de esa llamada. Ambos límites son opcionales con valores predeterminados: cero o la ausencia de valor aplica el límite predeterminado de la plataforma. El cargador limita cada plugin al valor predeterminado de la plataforma cuando la entidad no declara ninguno, así que una carga nunca es ilimitada y una llamada nunca es imposible de cancelar. Aumenta un límite en la entidad cuando una vinculación realmente necesite más memoria o más tiempo de lo que permite el valor predeterminado.

Funciones host. hostFunctions registra los nombres de las funciones host que importa el plugin. Es un campo derivado por máquina — no lo escribas. aggrega plugin sync lee las funciones host directamente de la sección de importaciones del .wasm y registra el campo en el archivo de la entidad por ti, y la publicación las vuelve a derivar del binario y rechaza una entidad cuyo registro difiere; así, un plugin obtiene exactamente las funciones host que su binario importa realmente, validadas contra una lista de permitidos seleccionada (una importación fuera de la lista de permitidos se rechaza de forma manifiesta). El registro es una instantánea del binario publicado, del mismo modo que la referencia plugin: direccionada por contenido es una instantánea de los bytes publicados: refleja el binario en el momento de la publicación y se vuelve a derivar y a verificar cuando se hace pull del plugin. Para ver las funciones host que importa un .wasm local antes de publicarlo — el valor que registra aggrega plugin sync — ejecuta aggrega inspect --plugin <file.wasm>.

La superficie host seleccionada. Tres de las funciones host son de uso general: aggrega_log (un nivel y un mensaje, emitidos como una línea de registro en el destino de registro del host), aggrega_emit_warning (un código, un mensaje y una ruta, acumulados como una advertencia estructurada que el host muestra después de la llamada) y aggrega_fetch_external_input (una URL, a la que se responde con los bytes de la entrada bajo la disciplina de fijación que se describe más abajo). El PDK envuelve las tres en cada lenguaje — Go: aggrega.Log, aggrega.EmitWarning, aggrega.FetchExternalInput; Rust: log, emit_warning, fetch_external_input; TypeScript: log, emitWarning, fetchExternalInput — así que un guest llama a una función tipada en lugar de a la ABI en bruto. Los callbacks de fuente y de análisis — para un guest que lee porciones de una fuente adquirida u obtiene un árbol analizado a través del host — y la codificación que llevan las ranuras de cada callback se enumeran en plugin-contract.md.

El contenido de la fuente local llega a través del host — nunca desde el sistema de archivos. Un plugin de renderizado de proveedor nunca lee su fuente del disco; una llamada al sistema de archivos falla en el límite de la llamada. El host entrega al guest un listado de la fuente dentro de la carga útil de renderizado — la ruta de cada entrada relativa a la raíz de la fuente y si es un directorio, en un orden fijo, sin contenido de archivos — y el guest le aplica su propia lógica de estructura y después vuelve a leer exactamente los archivos que selecciona mediante los callbacks de fuente, que devuelven los bytes que el host lee bajo la raíz de la fuente. Las formas de carga útil por socket y los callbacks se documentan en plugin-contract.md.

El contenido remoto llega a través de la obtención de entradas externas. Un plugin que necesita contenido remoto — un archivo de chart, un documento de esquema remoto — llama al wrapper de obtención del PDK. En la transmisión, el guest pasa la URL a aggrega_fetch_external_input como texto UTF-8 y recibe una única respuesta en CBOR canónico, que lleva o bien los bytes obtenidos, en bruto, o bien un mensaje de error junto a su código comparable por máquina; el wrapper decodifica la respuesta en bytes o error. Los bytes llegan exactamente como se obtuvieron, incluida una carga útil que no es UTF-8 válido, y una carga útil de longitud cero vuelve como bytes vacíos en lugar de como un error. El host sirve la URL bajo la disciplina de fijación de entradas externas:

  • Una URL ya fijada en el archivo de bloqueo de la Release se sirve desde el almacén local direccionado por contenido y se verifica contra su digest registrado en cada lectura. Un blob que falte en el almacén se vuelve a obtener de la red mediante el digest registrado — una reposición verificada por digest no puede cambiar la salida.
  • Una URL no fijada se rechaza, con un error que nombra la URL y la solución. Una compilación renderiza el cierre que registra su archivo de bloqueo, así que ninguna compilación obtiene una referencia no fijada y no existe ninguna configuración que lo haga posible.
  • La fijación se produce cuando se resuelven las dependencias de la Release: aggrega pull renderiza la Release para averiguar qué entradas externas solicita su renderizado, obtiene cada una y la registra en el archivo de bloqueo junto a las fijaciones de dependencias. Así que el ciclo de trabajo del autor de un plugin es: resolver una vez y luego compilar sin conexión tantas veces como quieras.

Los esquemas permitidos son https, http solo hacia hosts de loopback, y oci (fijado por el digest del manifiesto). El archivo de bloqueo registra cada entrada fijada — su URL, su digest sha256, su tamaño y los plugins que la requirieron — así que una nueva compilación sirve los mismos bytes desde el almacén local: reproducible y sin conexión una vez fijada.

Con el PDK de Go:

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)
}

Qué falla, y por qué.

  • Una llamada al sistema de archivos o a la red falla en el límite de la llamada: el guest no tiene directorios preabiertos ni sockets. Esto se aplica a todas las rutas de código, incluida una dependencia de biblioteca que intente leer un archivo — lee en su lugar la fuente mediante los callbacks de fuente.
  • Una importación bajo un módulo distinto de wasi_snapshot_preview1, extism:host/env y extism:host/user falla en la carga, con un diagnóstico que nombra el módulo y la importación. Los nombres individuales de funciones WASI dentro de un módulo permitido nunca se censuran — las importaciones de sistema de archivos y de sockets sin usar del runtime de un lenguaje enlazado estáticamente no son un problema, porque nombrar una importación no concede nada.
  • La obtención de una URL que el archivo de bloqueo no fija falla con un error que nombra la URL; la solución es ejecutar aggrega pull --release <release>, que fija cada entrada externa que consume el renderizado de la Release, y después compilar.

No existe ningún campo de lista de hosts permitidos para el acceso saliente a la red. Un plugin nunca llega a la red en tiempo de compilación — ese es el límite ahead-of-time — así que no existe ningún campo así que escribir. El contenido remoto llega a través del canal de entradas externas mediado por el host y fijado por digest descrito arriba, nunca a través de un acceso ambiental a la red.

Configuración. configKV es un mapa de cadena a cadena que el runtime entrega al plugin al iniciarse. Las entradas conservan el orden del autor, así que el registro emitido es idéntico byte a byte entre ejecuciones. Si está ausente, sigue vigente la configuración vacía predeterminada del runtime.

5. La entidad Plugin

Un plugin entra en el catálogo como una entidad Plugin — la superficie de creación y de metadatos del plugin. La entidad declara qué es el plugin y apunta al artefacto .wasm; el compilador no interpreta el comportamiento del plugin y encamina la referencia fijada, mientras que el runtime Wasm ejecuta los bytes.

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

Los campos:

  • Ningún campo de ubicación del artefacto, deliberadamente. La entidad no lleva ningún puntero al .wasm y el esquema no acepta ninguno. La ubicación del artefacto de un plugin se deriva de su identidad — la coordenada metadata.pluginType/metadata.name, que forma la ruta del repositorio plugin/<pluginType>/<name> — más el registro para el que esté configurado el espacio de trabajo, así que no hay ninguna ubicación que escribir ni en la que equivocarse. El digest de contenido resuelto se registra por Release en el archivo de bloqueo de esa Release, y la compilación verifica contra él los bytes obtenidos: la identidad en la entidad, los bytes verificados en el archivo de bloqueo.
  • metadata.version — la release que publica la entidad, que tiene que ser igual a la versión de procedencia de compilación del propio guest tal como la informa describe(). El autor de un plugin versiona el .wasm en tiempo de compilación — la compilación estampa la versión en el guest, y una compilación que la toma de un tag de release estampa la versión de la release solo en el commit que nombra ese tag — y el metadata.version de la entidad nombra esa misma release. El control de publicación contrasta ambas y se detiene ante una divergencia, así que la entidad siempre nombra la versión exacta del binario que distribuye. aggrega plugin gen-catalog --plugin (más abajo) copia la versión que informa el guest en la entidad que genera, que es la versión de la release cuando el guest se compiló a partir del commit etiquetado. Obligatorio.
  • metadata.pluginType — el tipo de socket que implementa este plugin, elegido entre provider, linter, pipeline-step, governance, cli, parser e importer. Un plugin implementa exactamente uno. Se encuentra en el bloque de direccionamiento junto a name y version y aporta el segmento <pluginType> de la coordenada derivada. Obligatorio.
  • spec.abiVersion — la versión de la ABI host/guest a la que se dirige el plugin. v1beta1 es el valor aceptado; una futura revisión de la ABI añade un valor aceptado. Obligatorio.
  • El bloque de tu tipo de socket, que lleva capabilities — un plugin declara lo que sirve dentro del bloque que pertenece a su metadata.pluginType, y es el bloque lo que fija qué significa una entrada. spec.provider.capabilities nombra las capacidades que sirve un proveedor (nombres de capacidades como helm o compose). spec.pipelineStep.capabilities nombra los proveedores con cuya salida renderizada es compatible tu paso. spec.parser.capabilities nombra los formatos de fuente que lee un analizador, cada uno escrito parse:<format>. spec.importer.capabilities nombra los formatos externos a partir de los cuales un importador redacta borradores de entidades, cada uno escrito import:<format>. Un importador escrito en Go puede tomar todo lo que no depende de su formato — la puntuación, la decisión de referenciar o de redactar un borrador, los borradores y su renderizado, y su configuración — del paquete importer del kit de Go, github.com/aggrega-ai/aggrega-pdk/go/pkg/importer. Un plugin linter, governance o cli no sirve ninguna capacidad y no lleva ninguno de los cuatro bloques. Las entradas conservan el orden del autor, y cada lista es una declaración explícita y probada: declara aquello contra lo que realmente has compilado y probado el plugin, porque un consumidor resuelve exactamente contra lo que está listado. Para un paso de pipeline, esa declaración se aplica en el renderizado — cuando un paso toca un ámbito, la compilación se detiene a menos que el proveedor que renderiza los documentos de ese ámbito esté entre los que declara tu plugin — así que una lista vacía no coincide con ningún proveedor y no admite el paso en ninguna parte.
  • spec.signature — un puntero descriptivo opcional a la firma adjunta del plugin (sección 8). Este bloque es solo documentación: registra dónde está la firma y cómo se produjo, para los lectores del catálogo; no admite por sí mismo el plugin. La comprobación que se aplica es la política de confianza por registro aplicada en el pull.
  • spec.runtime — el bloque opcional de restricciones de ejecución de la sección 4. El autor escribe maxMemoryPages, timeoutMs y configKV; hostFunctions se deriva por máquina y lo registra aggrega plugin sync, algo que la publicación verifica, y no lo escribe el autor.
  • spec.exports — las declaraciones de capacidad por export de la sección 3 (name, operates, scope, selector).

Generar la entidad a partir de tu .wasm. No tienes que escribir a mano las partes de la entidad gestionadas por la máquina. aggrega plugin gen-catalog --plugin <file.wasm> lee el autoinforme describe() del guest y produce a partir de él una entidad Plugin lista para publicar, más una pequeña superposición que escribes tú (la identidad, los límites de ejecución y cualquier bloque de proveedor). El generador estampa los campos de los que el binario es la fuente de verdad — las declaraciones de export, el contrato de capacidades, el espejo de comandos y el registro de funciones host — y copia metadata.version de la versión de procedencia de compilación de describe() del guest, mientras que la superposición aporta solo lo que el binario no informa. Esta es la vía admitida para el autor de un plugin de terceros: compila y versiona tu .wasm y después regenera la entidad para que sus campos gestionados por la máquina se mantengan sincronizados con el binario. La versión es el único campo copiado que nombra una release en lugar de un hecho sobre los bytes, así que genera a partir de una compilación del commit que nombra el tag de la release — o, partiendo de una compilación de desarrollo, establece metadata.version en la release dentro de la entidad generada antes de etiquetar el commit que la contiene. Un guest que no lleva ninguna versión de procedencia de compilación no puede generarse como una entidad versionada — versiona primero el guest en tiempo de compilación.

El .wasm junto a su entidad. Mientras escribes un plugin, no hay nada publicado que una compilación pueda descargar, así que una compilación lee el .wasm del plugin junto a su entidad Plugin en un directorio del catálogo, con un nombre derivado del tipo de plugin y del nombre de la entidad: para pipeline-step/patch es pipeline-step--patch.wasm. Las letras minúsculas, los dígitos y la mayoría de los guiones se escriben en ese nombre tal como son; cualquier otro carácter se escribe en forma escapada, y también un guion en algunas posiciones — así que, donde importa, el rechazo de un .wasm ausente, A plugin’s .wasm is not on this machine (El módulo de un plugin no está en esta máquina), da el nombre completo. aggrega lint <plugin.yaml> lee el .wasm del mismo lugar — junto al archivo de entidad que recibe, en cualquier directorio en que se encuentre ese archivo — salvo que el binario contenga el propio plugin, e imprime un aviso por cada export, capacidad o contrato que el .wasm informa y que la entidad omite. Donde no hay ningún .wasm, el lint indica que omitió ese informe, nombrando el archivo que buscó y el directorio, y su resultado no cambia.

Para la referencia campo por campo, consulta la página de la entidad ../entities/plugin.md.

6. Hacer referencia a un plugin

Un paso de pipeline o un socket de plugin hace referencia a un plugin mediante su URI de entidad Plugin — la identidad de la entidad, no directamente el artefacto .wasm. La entidad es la capa que lleva la fijación por digest, las declaraciones de capacidad, los límites de ejecución y la firma; hacer referencia a la entidad es la forma en que un consumidor recibe todo ello.

Una ruta .wasm sin más o una referencia de artefacto en bruto dejada en un campo plugin se rechaza en la carga: ninguna entidad Plugin coincide con ella, así que la resolución del plugin falla de forma manifiesta. La URI de la entidad es obligatoria — la indirección a través de la entidad es el contrato, no una comodidad opcional. Un paso de pipeline de una FeatureRecipe nombra la entidad en pipeline[].plugin; consulta ../entities/featurerecipe.md para la superficie de creación del pipeline.

Cuando dos o más plugins están acoplados — deben acordar un contrato de transferencia compartido, como en un par Fetcher e Injector en el que la salida de un plugin es la entrada del otro (el principio del Plugin en dos partes descrito en plugin-contract.md) — escribe ese contrato una sola vez y haz que cada plugin dependa de la definición única, en lugar de reformular de forma independiente la forma JSON de la transferencia en cada plugin. La forma compartida es la estructura JSON que intercambian los plugins, que puede residir en una única entrada de SchemaLibrary a la que hagan referencia ambos plugins. Una única fuente para el contrato mantiene sincronizados los plugins acoplados a medida que evoluciona; las reformulaciones independientes divergen, y la divergencia solo aflora cuando los dos dejan de coincidir en tiempo de ejecución. La recomendación es compartir el contrato, no el código Wasm — cada plugin sigue siendo su propio artefacto.

7. El ciclo de vida publish → pull → build

Un plugin pasa de un archivo .wasm en disco a un artefacto verificado y consumible por una compilación a través de tres etapas.

Publish. aggrega push publica una entidad Plugin y su .wasm juntos como un único manifiesto OCI, etiquetado con metadata.version: el YAML de la entidad es el blob de configuración del manifiesto y el .wasm viaja como una capa del mismo manifiesto. Publicar el par como un único manifiesto etiquetado es lo que hace atómico el push — no existe ninguna ventana en la que una mitad esté publicada y la otra no — y es la razón por la que una sola firma sobre ese manifiesto cubre ambas mitades. Ambas mitades se nombran en el manifiesto, así que un cliente OCI genérico que obtiene el tag de versión escribe la entidad en entity.yaml y el ejecutable en entity.wasm.

Antes de que llegue ningún byte, la publicación ejecuta sus comprobaciones. La entidad se lee primero contra el esquema Plugin, del modo en que la lee una carga del catálogo, así que un metadata.version que no es una versión semántica — o cualquier otra desviación del esquema — se rechaza antes de leer el .wasm. Después se carga el .wasm y su autoinforme describe() se contrasta con las declaraciones de capacidad escritas en la entidad — una discrepancia provoca una detención manifiesta, así que una entidad publicada nunca declara lo que el plugin que distribuye no informa. Se rechaza un guest cuya versión de procedencia de compilación en describe() lleva la marca -dirty con la que se estampa una compilación hecha desde un árbol de trabajo con cambios sin confirmar: esa versión nombra un commit que no contiene lo que se compiló. Se publican una versión de desarrollo compilada a partir de un commit (1.0.0-3-g1a2b3c4) y una versión preliminar (1.0.0-rc.1). El metadata.version registrado se contrasta con la versión de procedencia de compilación de describe() del guest, y una divergencia detiene la publicación, así que ambas deben coincidir. Los dos rechazos se resuelven del mismo modo: compila el plugin a partir de un checkout limpio del commit que nombra el tag de la release, para que informe él mismo de la versión de la release — para una release nueva, haz commit de la entidad con la fuente que publica y etiqueta primero ese commit. Copiar en la entidad la versión que informa una compilación de desarrollo no es una reparación: publica esa compilación con una versión que ningún tag de release nombra. Las funciones host que importa el .wasm se derivan del binario y se comparan con el registro confirmado en spec.runtime.hostFunctions; una divergencia detiene la publicación y nombra aggrega plugin sync, que vuelve a registrar el campo, porque el campo lo gestiona la máquina y una publicación nunca reescribe el archivo de la entidad confirmado. La entidad publicada lleva el registro estampado de funciones host; el digest de contenido del .wasm es una propiedad del manifiesto con el que se publica el par, y se registra para un consumidor en el archivo de bloqueo de la Release en lugar de escribirse en la entidad.

Pull. aggrega pull resuelve todas las dependencias de una Release y escribe un archivo de bloqueo por Release que fija cada entidad del catálogo y cada artefacto remoto a una versión y un digest de contenido. Un Plugin publicado se resuelve mediante esta resolución de dependencias; su .wasm se obtiene con el manifiesto que lo lleva y los bytes se verifican contra el digest de contenido que registra el archivo de bloqueo. El pull también vuelve a derivar las funciones host del .wasm verificado y las comprueba contra el registro hostFunctions estampado, y se detiene si ambos no coinciden — una comprobación de defensa en profundidad sobre la fijación por digest que detecta un binario cuyo registro estampado no se produjo a partir de sus propias importaciones. Si la política de confianza del registro exige firmas, la firma de la entidad se obtiene y se verifica en esta etapa, y se registra como un hecho verificado en el archivo de bloqueo (sección 8). La verificación ocurre en el pull, nunca en la compilación — la compilación sigue siendo pura ahead-of-time.

Build. aggrega build consume el plugin fijado y verificado de las dependencias resueltas. El compilador encamina la referencia fijada por digest y el runtime Wasm ejecuta los bytes; el control de carga vuelve a ejecutar la verificación cruzada con describe() y la aplicación de las funciones host y de los límites de ejecución antes de que se ejecute el plugin.

8. Firma y confianza

Una entidad Plugin se firma exactamente como cualquier otra entidad del catálogo: el digest del manifiesto se firma y se adjunta como referrer OCI. El artefacto .wasm no se firma por separado, y no necesita una firma aparte — es una capa del mismo manifiesto cuyo digest se firma, así que la firma lo cubre directamente: manipular el .wasm cambia el digest del manifiesto y rompe la firma.

La firma es de adopción voluntaria en la publicación; la verificación la aplica la política de confianza por registro en el pull. Un registro configurado para exigir firmas detiene el pull cuando falta una firma requerida, no es de confianza o no es válida. El bloque spec.signature de la entidad es un puntero de documentación a dónde está la firma y cómo se produjo; registra hechos para los lectores del catálogo y no controla por sí mismo la admisión. El punto de control es la política en el momento del pull.

Los comandos y sus indicadores se documentan con las superficies de publicación y de consumo — consulta ../cli/aggrega-sign.md, ../cli/aggrega-push.md y ../cli/aggrega-pull.md. Esta guía no repite las tablas de indicadores; esas páginas son el único lugar de la superficie de comandos.

9. Versionar la entidad

Una entidad Plugin lleva una Semantic Version estricta en metadata.version. Una versión publicada es inmutable: volver a publicar una versión que ya existe en el registro con un contenido distinto se rechaza en el control de publicación.

Cuando cambias una entidad de plugin y vuelves a publicarla, la disciplina de publicación clasifica el cambio respecto a la versión publicada anteriormente y exige que el incremento de versión coincida. La clasificación sigue la rúbrica de incremento de versión: un cambio solo de documentación o de comentarios es PATCH; un cambio estrictamente aditivo (un campo opcional nuevo, una entrada nueva) es MINOR; una eliminación, un estrechamiento de tipo o un campo antes opcional que pasa a ser obligatorio es MAJOR. Un incremento excesivo siempre está permitido; un incremento insuficiente se detiene con un diagnóstico que nombra el incremento requerido. La primera publicación de una entidad omite la comprobación del incremento y muestra una advertencia de que no se realizó ninguna verificación. Ejecuta la comprobación antes de publicar con aggrega lint --pre-publish; consulta ../cli/aggrega-lint.md para la rúbrica completa y la configuración por regla.

Un Plugin no tiene superficie extends, así que las reglas de herencia que rigen los Components y las Features del catálogo no lo alcanzan. La rúbrica de incremento de versión y la inmutabilidad son la disciplina de versionado que rige una entidad de plugin.

10. Referencias cruzadas

  • authoring-a-provider-walkthrough.md — un guest de proveedor construido de principio a fin, desde un directorio vacío hasta la salida renderizada.
  • plugin-contract.md — los puntos de socket a los que se dirige un plugin y las formas de entrada/salida por socket.
  • policy-socket.md — el socket de gobernanza en profundidad: sus cuatro roles, las severidades de los veredictos, el canal de entrada del operador, cómo escribir una política para cualquiera de los dos motores que se incluyen en el compilador y los guests de políticas de referencia.
  • core-importers.md — los importadores propios del compilador, uno para cada formato que lee, construidos sobre el paquete importer del kit de Go: qué lee cada uno, su configuración y su publicación con cada versión del compilador.
  • ../compatibility.md — cómo se versionan los kits de plugins y qué hace que un plugin compilado para una versión siga cargándose en la siguiente.
  • ../entities/plugin.md — la referencia campo por campo de la entidad Plugin.
  • ../entities/featurerecipe.md — la superficie de creación pipeline: de la FeatureRecipe que hace referencia a un plugin por URI de entidad.
  • ../cli/aggrega-lint.md — el publishing-linter, la rúbrica de incremento de versión y la aplicación de la inmutabilidad.
  • ../cli/aggrega-inspect.md — la inspección de las capacidades, los límites de ejecución y la firma de una entidad Plugin.
  • ../cli/aggrega-push.md, ../cli/aggrega-pull.md, ../cli/aggrega-sign.md — las superficies de comandos de publicación, de consumo y de firma.