Escribir un proveedor: una guía paso a paso con un ejemplo
Esta página recorre toda la tarea de escribir un guest de proveedor, desde un directorio vacío hasta una compilación que escribe los archivos que el proveedor renderizó. Es el complemento práctico de la guía para desarrolladores de plugins, que documenta la entidad y el ciclo de vida, y del contrato de plugins, que documenta los sockets.
El proveedor que se construye aquí es lo bastante pequeño como para leerlo de una sentada y hace un trabajo real: renderiza archivos de entorno. Ese destino es un buen primer proveedor porque su traducción es genuinamente específica del formato — un archivo de entorno tiene su propia gramática de claves, sus propias reglas de comillas y ningún bloque de metadatos donde poner la procedencia de la compilación —, así que el guest tiene que tomar cada decisión que toma un proveedor más grande, sin un gran cuerpo de código que las oculte.
Sobre los bloques de esta página. Cada bloque que muestra una salida se copió de una ejecución real de los pasos siguientes, en el orden en que aparecen, según la convención de salida: un bloque está completo o es un extracto que marca dónde se omitieron líneas. Esta es una guía que ensamblas tú mismo, no un espacio de trabajo que puedas clonar, así que los bloques de código fuente son los archivos que hay que crear, no archivos que haya que obtener del repositorio.
Lo que necesitas
- La cadena de herramientas de Go, que compila a WebAssembly sin herramientas adicionales.
- Un checkout del kit de desarrollo de plugins, que presenta la guía para desarrolladores de plugins, y del paquete ABI en el que se basa el kit: el
go.moddel guest que aparece más abajo apunta a ambos. - El binario
aggrega.
La estructura del resultado final
Un proveedor son dos artefactos: un guest .wasm y una entidad Plugin que lo lleva a un catálogo. Nada más — ningún cambio en el host, ninguna inscripción, ninguna compilación del compilador. Añadir un proveedor es añadir esos dos archivos donde una compilación pueda verlos.
El espacio de trabajo con el que termina esta guía:
dotenv-walkthrough/ guest/ the Go module that compiles to the .wasm go.mod go.sum main.go catalog/ the Component and Recipe you author component/example/compute/checkout/1.0.0/component.yaml recipe/dotenv/checkout/1.0.0/recipe.yaml dev-catalog/ the generated Plugin entity, with the .wasm beside it plugin/provider/dotenv/0.1.0/plugin.yaml plugin/provider/dotenv/0.1.0/provider--dotenv.wasm dotenv.wasm the compiled guest overlay.yaml the identity you supply to the entity generator aggregate.yaml manifest.yaml release.yaml .aggrega-config.yaml1. La autodescripción del guest
Cada plugin exporta describe(). El host lo llama una vez cuando carga el guest y lee la respuesta como la descripción que el guest da de sí mismo. Para un proveedor importan cuatro partes de esa respuesta.
Crea guest/main.go:
// A provider guest that renders environment-file artifacts.package main
import ( "bytes" "fmt" "sort" "strings"
pdk "github.com/extism/go-pdk"
"github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega")
func descriptor() aggrega.PluginDescriptor { return aggrega.PluginDescriptor{ AbiVersion: aggrega.APIVersion, PluginType: "provider", Description: "Render artifact bodies into environment files, quoting and escaping each value as the format requires.", Capabilities: []string{"dotenv"}, Exports: []aggrega.PluginExport{ {Name: "render_node"}, }, Metadata: &aggrega.PluginDescriptorMeta{License: "Apache-2.0"}, }}
//go:wasmexport describefunc describe() int32 { out, err := aggrega.MarshalDescriptor(descriptor()) if err != nil { pdk.SetError(err) return 1 } pdk.Output(out) return 0}PluginType indica a qué socket sirve este guest. Capabilities es la lista con la que se resuelve una Recipe: una Recipe cuyo spec.capability es dotenv se enrutará a este guest. Exports nombra los puntos de entrada a los que el host puede despachar; render_node es el que todo proveedor debe tener.
Este descriptor está incompleto a propósito, como suele estarlo un primer borrador. La primera compilación, más abajo, es donde se pone de manifiesto.
2. Renderizar un nodo
render_node se llama una vez por cada componente que la compilación renderiza a través de este proveedor. Recibe la identidad del nodo, el contexto de renderizado y las entradas preevaluadas que declaró la Recipe enlazada — aquí, un conjunto de artefactos que el host ya leyó y evaluó como plantilla.
Todo el trabajo del guest es decidir qué bytes salen. Añade a guest/main.go:
// needsQuoting reports whether a value cannot be written bare in an// environment file. A bare value ends at the first space, so anything// carrying whitespace has to be quoted; the quote characters, the comment// introducer and the expansion introducer would each be read as syntax.func needsQuoting(v string) bool { if v == "" { return true } return strings.ContainsAny(v, " \t\n\r\"'#$\\")}
// quote wraps a value in double quotes and escapes what the format reads as// syntax inside them. Order matters: the backslash is escaped first, or the// escapes introduced afterwards would be escaped a second time.func quote(v string) string { v = strings.ReplaceAll(v, `\`, `\\`) v = strings.ReplaceAll(v, `"`, `\"`) v = strings.ReplaceAll(v, "\n", `\n`) v = strings.ReplaceAll(v, "\r", `\r`) v = strings.ReplaceAll(v, "\t", `\t`) return `"` + v + `"`}
// normaliseKey maps an authored key into the environment-variable grammar:// upper case, with the separators an author reaches for folded to// underscores. It reports an error rather than correcting a key that still// does not fit, because a silently-renamed variable is one the application// never reads.func normaliseKey(k string) (string, error) { n := strings.ToUpper(k) n = strings.NewReplacer("-", "_", ".", "_", "/", "_").Replace(n) if n == "" { return "", fmt.Errorf("empty key") } for i, r := range n { switch { case r >= 'A' && r <= 'Z', r == '_': case r >= '0' && r <= '9' && i > 0: default: return "", fmt.Errorf("key %q maps to %q, which is not a valid environment-variable name", k, n) } } return n, nil}Tres decisiones de ese fragmento son propias del proveedor, y ninguna otra capa podría tomarlas. Qué caracteres obligan a usar comillas es un hecho de los archivos de entorno. También lo es la gramática de los nombres de variable, y también la decisión de rechazar una clave que no encaja en lugar de renombrarla — una variable renombrada es una que la aplicación buscará y no encontrará, lo cual es peor que una compilación detenida.
Ahora las dos piezas restantes: adónde va la procedencia, y la exportación en sí.
// provenanceComment renders the build-provenance key set the host computed as// comment lines. An environment file has no metadata block, so a comment// header is where provenance can go; the keys are emitted in sorted order so// the bytes are identical across runs of identical input.func provenanceComment(annotations map[string]string) []byte { if len(annotations) == 0 { return nil } keys := make([]string, 0, len(annotations)) for k := range annotations { keys = append(keys, k) } sort.Strings(keys) var out bytes.Buffer for _, k := range keys { fmt.Fprintf(&out, "# %s=%s\n", k, annotations[k]) } out.WriteByte('\n') return out.Bytes()}
// renderBody translates one artifact body into environment-file lines. A// blank line and a comment pass through untouched; every other line is// KEY=value, and a line carrying no separator is a loud failure rather than a// line the guest guesses at.func renderBody(name string, body []byte) ([]byte, error) { var out bytes.Buffer for i, raw := range strings.Split(string(body), "\n") { line := strings.TrimSpace(raw) if line == "" || strings.HasPrefix(line, "#") { continue } k, v, found := strings.Cut(line, "=") if !found { return nil, fmt.Errorf("%s line %d: %q declares no value; an entry is KEY=value", name, i+1, line) } key, err := normaliseKey(strings.TrimSpace(k)) if err != nil { return nil, fmt.Errorf("%s line %d: %w", name, i+1, err) } val := strings.TrimSpace(v) if needsQuoting(val) { val = quote(val) } fmt.Fprintf(&out, "%s=%s\n", key, val) } return out.Bytes(), nil}
//go:wasmexport render_nodefunc render_node() int32 { var in aggrega.RenderNodeInput if err := in.DecodeCBOR(pdk.Input()); err != nil { pdk.SetError(fmt.Errorf("dotenv: decode RenderNodeInput: %w", err)) return 1 }
if in.ArtifactsProjection == nil || len(in.ArtifactsProjection.Entries) == 0 { pdk.SetError(fmt.Errorf("dotenv: node %q supplied no artifacts to render", in.Node.ID)) return 1 }
var files []aggrega.RenderedFile for _, e := range in.ArtifactsProjection.Entries { body, err := renderBody(e.Name, e.Content) if err != nil { pdk.SetError(fmt.Errorf("dotenv: %w", err)) return 1 } files = append(files, aggrega.RenderedFile{ Path: e.Name, Content: append(provenanceComment(e.Annotations), body...), Format: "text", }) }
outputBytes, err := aggrega.RenderNodeOutput{Files: files}.EncodeCBOR() if err != nil { pdk.SetError(fmt.Errorf("dotenv: encode RenderNodeOutput: %w", err)) return 1 } pdk.Output(outputBytes) return 0}
func main() {}La carga útil viaja en una codificación binaria, y el kit la lee y la escribe. El host entrega a render_node su entrada como CBOR canónico y lee la respuesta en la misma codificación, así que el guest decodifica con el DecodeCBOR del tipo de entrada y codifica con el EncodeCBOR del tipo de salida — ninguna biblioteca CBOR, y nada analizado a mano. El Content de un archivo es un slice de bytes que el guest llena con los bytes exactos que hay que escribir; el codificador los transporta como bytes en bruto y el host los escribe tal cual.
El host entrega al guest contenido que ya ha evaluado. El Content de cada entrada de artefacto es el cuerpo escrito por el autor con sus expresiones de plantilla ya resueltas frente al contexto de renderizado — el guest nunca evalúa una plantilla y nunca lee un archivo. Eso es lo que mantiene intacto el límite de compilación anticipada del compilador: el guest es una función pura de la carga útil a bytes.
El determinismo es responsabilidad del guest. En una compilación normal nada lo comprueba por ti. Aquí proviene de ordenar las claves de procedencia antes de emitirlas y de recorrer las entradas de artefacto en el orden en que las lleva la carga útil, y las comprobaciones cerca del final de esta página miden el resultado.
guest/go.mod hace referencia a tu checkout del kit:
module example.com/dotenv-provider
go 1.26.0
require ( github.com/aggrega-ai/aggrega-pdk/go v0.0.0 github.com/extism/go-pdk v1.1.3)
require github.com/aggrega-ai/aggrega-abi/go v0.0.0 // indirect
replace github.com/aggrega-ai/aggrega-pdk/go => /path/to/aggrega-pdk/go
replace github.com/aggrega-ai/aggrega-abi/go => /path/to/aggrega-abi/go3. Compilar el guest
Un guest es una compilación normal de Go con el destino WebAssembly seleccionado:
cd guestgo mod tidyGOWORK=off GOOS=wasip1 GOARCH=wasm go build -trimpath -buildvcs=false \ -ldflags "-X github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega.Version=0.1.0 \ -X github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega.Commit=walkthru" \ -buildmode=c-shared -o ../dotenv.wasm ./go mod tidy escribe go.sum, las sumas de comprobación de las dependencias, sin el cual la compilación se niega a ejecutarse. -trimpath y -buildvcs=false mantienen fuera del binario las rutas de compilación y las marcas del control de versiones, así que el mismo código fuente en el mismo commit produce los mismos bytes. Los dos valores de -ldflags estampan en el guest su propia versión, que lee el paso siguiente.
Confirma las exportaciones antes de seguir:
aggrega inspect --plugin dotenv.wasmPlugin .wasm: dotenv.wasmExports: render_nodehostFunctions (derived from binary, not yet recorded by aggrega plugin sync): (none)Este guest no importa funciones host, que es la opción predeterminada de mínimo privilegio: no necesita ni el sistema de archivos ni la red, porque todo lo que renderiza llega en la carga útil.
4. Generar la entidad Plugin
Los campos de contrato de la entidad no se escriben a mano — se leen del guest para que la entidad no pueda prometer algo que el binario no hace. Tú solo aportas la identidad, en una pequeña superposición.
overlay.yaml:
apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: dotenvaggrega plugin gen-catalog --plugin dotenv.wasm \ --overlay overlay.yaml --output-dir dev-catalog/plugingenerated dev-catalog/plugin/provider/dotenv/0.1.0/plugin.yamlLa entidad generada:
# Generated from the plugin by `aggrega plugin gen-catalog`. You may narrow its capability lists; edit nothing else here.apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: dotenv version: 0.1.0 pluginType: provider description: Render artifact bodies into environment files, quoting and escaping each value as the format requires.spec: abiVersion: v1beta1 exports: - name: render_node provider: capabilities: - dotenvFíjate en lo que no está: ningún puntero al .wasm. La ubicación de un plugin se deriva de su identidad — la coordenada pluginType/name más el registro que esté configurado —, así que no hay ningún campo de ubicación que escribir ni ninguno en el que equivocarse. El digest del contenido se registra cuando se resuelve una Release, en el archivo de bloqueo de esa Release, no en la entidad.
5. Poner el guest donde una compilación lo buscará
Mientras desarrollas un guest no hay nada publicado que descargar, así que la compilación lo lee de un directorio de catálogo: el .wasm situado junto a su entidad, con un nombre que indica el socket y el plugin.
dev-catalog/plugin/provider/dotenv/0.1.0/plugin.yamldev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasmcp dotenv.wasm dev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasmEl nombre del archivo lleva el socket además del nombre porque un nombre de plugin a secas solo es único dentro de su propio socket — dos plugins llamados dotenv en sockets distintos tienen que llegar a dos archivos.
Copia allí el archivo compilado en lugar de enlazarlo. Un enlace en ese lugar solo se sigue hasta un destino dentro del espacio de trabajo — o, para un directorio de catálogo listado fuera del espacio de trabajo, dentro de ese directorio; uno que lleve más lejos detiene la compilación y el pull nombrando el enlace, como expone el límite del espacio de trabajo.
La entidad plugin de un proveedor en un directorio de catálogo nunca está fijada, y ni un pull ni una compilación descargan su .wasm, así que el archivo tiene que estar ahí cuando se resuelve la Release. Un pull comprueba antes de escribir el archivo de bloqueo: si no encuentra el .wasm ni junto a la entidad ni en ningún otro lugar desde el que una compilación lee plugins, se detiene y nombra el archivo y el directorio en el que lo esperaba, como describe A plugin’s .wasm is not on this machine (El archivo Wasm de un plugin no está en esta máquina).
Haz que el espacio de trabajo apunte a ambos directorios de catálogo en .aggrega-config.yaml:
workspace: catalog_dirs: - catalog - dev-catalogauto_pull: trueauto_pull permite que aggrega build resuelva la Release dentro del proceso, así que una primera compilación no necesita un paso de resolución aparte.
6. Los documentos que apuntan al proveedor
Cuatro archivos. El Component declara lo que un autor puede establecer; la Recipe enlaza la capacidad y define el artefacto; el Aggregate expresa la intención; la Release la ubica.
catalog/component/example/compute/checkout/1.0.0/component.yaml:
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: example/compute/checkout version: 1.0.0 description: An application whose configuration is delivered as an environment file. labels: component.aggrega.ai/type: server component.aggrega.ai/category: computespec: schema: values: service_name: type: string default: checkout description: The name the application reports itself under. log_level: type: string default: info description: The application's log verbosity. greeting: type: string default: hello description: A value carrying characters the environment-file format must quote. infra: endpoint: type: string default: http://localhost:8080 description: The endpoint the operator points the application at.catalog/recipe/dotenv/checkout/1.0.0/recipe.yaml:
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: checkout version: 1.0.0 description: Renders the application's configuration as an environment file.spec: capability: dotenv implements: example/compute/checkout:1.0.0
artifacts: app.env: | service-name = {{ .values.service_name }} log.level = {{ .values.log_level }} greeting = {{ .values.greeting }} endpoint = {{ .infra.endpoint }}spec.capability: dotenv es todo el enlace. Nombra una capacidad, no un plugin: la compilación la resuelve al plugin proveedor que declare esa capacidad. Donde hay exactamente uno — como aquí — no hace falta nada más.
Las claves escritas no están a propósito en forma de variable de entorno. service-name y log.level son las grafías que un autor escribiría de forma natural, y normalizarlas es trabajo del proveedor.
aggregate.yaml:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: aggregate version: "1.0.0" description: One application whose configuration is an environment file.spec: components: app: type: example/compute/checkout values: service_name: checkout log_level: debug greeting: hello worldmanifest.yaml:
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: manifest version: "1.0.0" description: Binds the component type to the environment-file recipe.spec: mappings: components: type: example/compute/checkout:1.0.0: checkout:1.0.0release.yaml:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: walkthrough environment: production version: "1.0.0"spec: aggregate: aggregate manifest: manifest boundaries: infra: directory: infra components: app: infra: endpoint: "https://checkout.example.net"7. La primera compilación, y lo que rechaza
aggrega build --release release.yaml --auto-pull warning: plugin "provider/dotenv" resolved from local with no recorded digest to check it against, so it runs unverified; it is read from beside its Plugin entity in a catalog directory on every build, and a pull records its digest only for a plugin attached at a transform role; otherwise publish the plugin and reference the published entity to have its digest recorded[… omitted: the notice saying the Release could not be rendered to discover its external inputs, carrying the error below beneath its first line]Pull complete: release.lock (entities=5, source_artifacts=0, external_inputs=0)[… omitted: a line saying again that external inputs were not fully discovered][CATALOG_ERROR E0265] instance app provider does not support the node's input kind (node "app"). provider "dotenv" does not support artifacts-only recipes (this provider supports: none); declare one of the supported input kinds, or target a provider that supports artifacts-onlyLee las dos líneas por separado, porque dicen cosas distintas.
La advertencia es esperable mientras desarrollas, y no desaparecerá. Dice que el guest se ejecutó sin un digest de contenido registrado con el que contrastarlo, que es la verdad de un guest que compilaste hace un minuto: nadie lo publicó, así que no hay ningún digest registrado. También dice por qué resolver de nuevo la Release no cambiaría eso — un guest leído junto a su entidad en un directorio de catálogo se vuelve a leer en cada compilación, y un pull registra su digest solo para un plugin de gobernanza vinculado en un rol de transformación, que este guest no es — y qué lo cambiaría: publicar el plugin y hacer referencia a la entidad publicada. Lee la advertencia como la compilación que se abstiene correctamente de afirmar una verificación que no realizó, y cuenta con ella mientras el guest sea local.
El error es el hallazgo real, y el paréntesis es el diagnóstico. El proveedor se encontró, se cargó y se le preguntó qué renderiza, y respondió none — this provider supports: none. El descriptor escrito al principio nombraba el socket, la capacidad y las exportaciones, pero nunca decía cuál de los tres tipos de entrada de Recipe maneja el guest. El host no adivina: el control de tipos de entrada lee el conjunto declarado por el guest y rechaza un nodo que el guest nunca reclamó.
Esta es la forma de la mayoría de los fallos de un primer proveedor. El guest está bien; su autodescripción está incompleta. describe() no es una formalidad que el host tolera — es toda la base sobre la que un host agnóstico respecto al formato decide qué enviar y adónde.
8. Declarar el contrato de comportamiento de renderizado
Añade el contrato al descriptor en guest/main.go:
Capabilities: []string{"dotenv"}, Contract: &aggrega.ProviderContract{ InputKinds: aggrega.InputKinds{ Sourced: false, Synthesized: false, ArtifactsStandalone: true, }, BoundaryAssembly: "none", }, Exports: []aggrega.PluginExport{ArtifactsStandalone: true es la afirmación que buscaba el control. Los dos valores false también son afirmaciones, y declararlos es justamente la idea: una Recipe que incorpora un árbol de código fuente, o una que declara una carga de trabajo, se rechaza ahora antes de que se ejecute cualquier renderizado, con un mensaje que nombra este proveedor — en lugar de llegar a render_node y fallar en algún punto dentro de él.
BoundaryAssembly: "none" indica que la salida de cada nodo se escribe donde cae, sin nada que combinar. Un proveedor que reúne varios componentes en un único documento declara en cambio merge o nest, y exporta assemble_boundary para hacerlo. Es lo siguiente natural que añadir a este proveedor, y está documentado en el contrato de plugins.
Vuelve a compilar el guest, regenera la entidad y vuelve a poner el nuevo .wasm junto a ella:
cd guestGOWORK=off GOOS=wasip1 GOARCH=wasm go build -trimpath -buildvcs=false \ -ldflags "-X github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega.Version=0.1.0 \ -X github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega.Commit=walkthru" \ -buildmode=c-shared -o ../dotenv.wasm ./cd ..aggrega plugin gen-catalog --plugin dotenv.wasm \ --overlay overlay.yaml --output-dir dev-catalog/plugincp dotenv.wasm dev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasmLa entidad regenerada lleva ahora el contrato, leído del binario:
[… omitted: the header comments and the metadata block, unchanged from the first generation]spec: abiVersion: v1beta1 exports: - name: render_node provider: capabilities: - dotenv contract: inputKinds: artifactsStandalone: true boundaryAssembly: noneRegenerar la entidad después de cada recompilación del guest forma parte del ciclo. La entidad repite lo que informa el binario, y ambos se contrastan cuando se carga el guest: una exportación o un valor de contrato que la entidad afirma y el binario no informa es una discrepancia por la que la compilación se detiene, nombrando la afirmación. Una afirmación que la entidad omite no se comprueba, así que una entidad que se quedó atrás tras una recompilación que añadió algo al binario — como hizo este paso — sigue cargándose, aunque ya no lo describa.
9. La compilación que renderiza
aggrega build --release release.yaml --auto-pull warning: plugin "provider/dotenv" resolved from local with no recorded digest to check it against, so it runs unverified; it is read from beside its Plugin entity in a catalog directory on every build, and a pull records its digest only for a plugin attached at a transform role; otherwise publish the plugin and reference the published entity to have its digest recordedPull complete: release.lock (entities=5, source_artifacts=0, external_inputs=0)[… omitted: a line reporting total build time, which differs on every run]Build completed: 1 file written to <workspace>/distLa línea final nombra el directorio de salida completo, donde <workspace> representa la raíz del espacio de trabajo. El árbol renderizado bajo él:
dist/infra/dotenv/app/app.envY el archivo que escribió el proveedor, completo:
# aggrega.ai/boundary-path=infraSERVICE_NAME=checkoutLOG_LEVEL=debugGREETING="hello world"ENDPOINT=https://checkout.example.netCada decisión que toma el guest es visible en esas siete líneas.
service-nameylog.levelllegaron tal como se escribieron y salieron comoSERVICE_NAMEyLOG_LEVEL. El autor nunca tuvo que escribir la gramática del destino.GREETINGva entre comillas y los otros tres no.hello worldcontiene un espacio, así que sin comillas terminaría enhello; el endpoint no contiene ninguno de los caracteres que el formato lee como sintaxis, así que ponerlo entre comillas solo añadiría ruido.- Las dos claves de procedencia son comentarios, porque un archivo de entorno no tiene ningún otro lugar donde ponerlas. Un proveedor cuya salida tiene un bloque de metadatos pone allí las mismas claves. El host calculó las claves; el guest eligió dónde colocarlas.
- Los valores provienen de dos autores distintos.
service_name,log_levelygreetingson la intención del desarrollador, del Aggregate.endpointes del operador, de la Release. El guest no vio ninguna de las dos distinciones — recibió un único cuerpo evaluado.
10. Dos cosas que conviene comprobar antes de confiar en él
Que es determinista. Captura la salida, vuelve a compilar y compara:
cp -r dist ../capture && rm -rf distaggrega build --release release.yamldiff -r ../capture distQue diff no imprima nada es el resultado que buscas. El determinismo es contrato del guest, no del host, y un guest que itere un mapa de Go en algún punto de su ruta de salida fallará esta comprobación aunque parezca perfectamente correcto en una sola compilación.
Que sus rechazos son visibles. Rompe una línea del artefacto de la Recipe, de modo que no declare ningún valor:
artifacts: app.env: | service-name = {{ .values.service_name }} this line declares no value[… omitted: the unverified-plugin warning, and the pull's lines saying the Release could not be rendered to discover its external inputs][CATALOG_ERROR] instance app rendering node "app" caused by: wasm: plugin "provider/dotenv:0.1.0" call to render_node: dotenv: app.env line 2: "this line declares no value" declares no value; an entry is KEY=valueEl propio mensaje del guest llega intacto al autor, con el archivo y la línea de los que procede. Merece la pena comprobarlo deliberadamente, porque el fallo alternativo — un guest que se salta en silencio una línea que no sabe analizar — produce una compilación que tiene éxito y una Release a la que le falta una variable, y nada en la salida lo indica.
11. Qué añadir a continuación
El proveedor construido aquí está completo pero es mínimo. En orden aproximado de la frecuencia con que se necesita cada uno:
-
assemble_boundary, para reunir la salida de varios componentes en un único documento, declarado medianteBoundaryAssembly. -
validate_node_input, para comprobar estructuralmente la entrada de un nodo antes de que se ejecute cualquier renderizado, de modo que una entrada mal formada se informe en el límite de la autoría y no a mitad del renderizado. -
Hechos de renderizado, para informar de algo sobre lo que escribió el guest que solo el conocimiento que este proveedor tiene del formato de los archivos de entorno puede ver — aquí, los nombres de variable que define cada archivo. Un hecho es un nombre y una lista, ambos del vocabulario propio de este proveedor, devueltos junto a los archivos — y el valor es siempre un array JSON, incluso con una sola entrada, o la compilación se detiene:
// names lists the variables the files define, in the order they were written.value, err := json.Marshal(names)if err != nil {pdk.SetError(fmt.Errorf("dotenv: marshal render fact: %w", err))return 1}out := aggrega.RenderNodeOutput{Files: files,RenderFacts: []aggrega.RenderFact{{Name: "variable_names", Value: value}},}El compilador conserva los hechos en el orden en que el guest los enumera, comprueba solo que cada valor sea una lista, entrega las listas a las plantillas de Feature que las leen y escribe los mismos archivos tanto si se informan como si no. Documenta el nombre de cada hecho y lo que contienen sus entradas como parte del contrato del proveedor.
-
Entradas de omisión, una vez que el proveedor renderiza una fuente. La entrada de un renderizado de fuente puede llevar
Omits, entradas que nombran unidades renderizadas que hay que dejar fuera, junto a suSourceListing; un proveedor que las respeta deja fuera de lo que devuelve cada unidad que coincida, informa de un recuento por entrada enOmittedy declaraOmits: trueen su contrato. Nunca acompañan a un renderizado solo de artefactos como el de este proveedor, así que solo se las encuentra después de renderizar una entrada con fuente. Omitir unidades renderizadas en el contrato de plugins tiene la estructura completa. -
Publicación, que convierte la disposición local
dev-catalogen un artefacto fijado por digest que una Release resuelve y verifica. La guía para desarrolladores de plugins cubre ese ciclo de vida, en las etapas de publicación, pull y compilación.
Las estructuras de la carga útil y del resultado de cada socket están en el contrato de plugins.
Referencias relacionadas
- Guía para desarrolladores de plugins Wasm — la entidad
Plugin, la superficie de capacidades y el ciclo de vida de la publicación. - Contrato del Plugin — las estructuras de entrada y salida de cada socket.
- Arquitectura de Provider — cómo encajan los proveedores en la canalización de compilación.
- Índice de referencia de Provider — qué produce cada proveedor de la biblioteca estándar.
- Leer la salida en estas páginas — la convención que siguen los bloques de salida anteriores.