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

Gramática de URI e inventario de cadenas de formato

Las entidades de Aggrega se referencian entre sí mediante cadenas URI que aparecen en varias posiciones de autoría distintas. La misma forma de URI (core/postgres:1.0.0) aparece en cinco o más contextos de tipo de entidad, y el compilador infiere el tipo de entidad a partir de la posición en el esquema en lugar de un sigilo o un prefijo. Los autores que leen o mantienen un archivo YAML deben tener presentes las reglas de interpretación basadas en la posición para saber si core/postgres:1.0.0 se refiere a un tipo de Component, un módulo Aggregate, una Recipe, una FeatureRecipe o un plugin Wasm.

Esta página reúne la gramática de URI en todas las posiciones, las reglas de precedencia para las claves type: con versión y sin versión en los niveles de mapeo del Manifest, las reglas de inferencia de las formas abreviadas de URI OCI y el inventario más amplio de cadenas de formato en todo el corpus (sintaxis de plantillas de Go, funciones de Sprig, declaraciones de JSON Schema 2020-12, JSONPath, patrones glob, regex de SemVer). Los autores que necesiten saber «¿qué hace Aggrega con esta cadena?» deberían encontrar aquí la respuesta.

Inferencia del tipo de entidad basada en la posición

La misma cadena URI tiene un significado de tipo de entidad distinto según dónde aparezca en el esquema. La tabla siguiente enumera cada posición en la que Aggrega espera un URI de referencia a una entidad, junto con el tipo de entidad inferido:

PositionTipo de entidad inferidoExpansión de la ruta OCI
Aggregate.spec.components.<id>.typeComponent/component/{publisher}/{category}/{name}
Aggregate.spec.subsystems.<name>.components.<id>.typeComponent (igual que components — los subsistemas son agrupaciones de componentes)/component/{publisher}/{category}/{name}
Aggregate.spec.aggregates.<id>.typeAggregate (módulo de subagregado)/aggregate/{publisher}/{name}
Aggregate.spec.components.<id>.features.<id>.typeFeature/feature/{publisher}/{name}
Aggregate.spec.components.<id>.features.<id>.typeFeature (credencial — etiquetada con feature.aggrega.ai/kind: secret)/feature/{publisher}/{name}
Manifest.spec.mappings.components.type.<key>Component (el URI usado como clave de búsqueda); el valor es un URI de Recipeclave: /component/; valor: /recipe/{provider}/{name}
Manifest.spec.mappings.components.name.<id>Recipe (vinculación granular de sobrescritura)/recipe/{provider}/{name}
Manifest.spec.mappings.features.type.<key>Feature (clave de búsqueda); el valor es un URI de FeatureRecipeclave: /feature/; valor: /featurerecipe/{provider}/{name}
Manifest.spec.mappings.features.name.<id>FeatureRecipe (vinculación granular de sobrescritura)/featurerecipe/{provider}/{name}
Manifest.spec.mappings.features.annotations.<key>.featureFeature (vinculada a una anotación)/feature/{publisher}/{name}
Recipe.spec.implementsComponent (contrato de interfaz)/component/{publisher}/{category}/{name}
FeatureRecipe.spec.implementsFeature (contrato de interfaz)/feature/{publisher}/{name}
Component.spec.extends / Feature.spec.extendsComponent / Feature (padre en la cadena de herencia)/component/{publisher}/{category}/{name} o /feature/{publisher}/{name}
Manifest.spec.extendsManifest (padre en la cadena de herencia de mapeos)no es una posición URI — una ruta relativa, o el metadata.name simple de un Manifest junto a la Release
Release.spec.extendsRelease (padre en la cadena de herencia)no es una posición URI — una ruta relativa a un archivo de Release, y ninguna otra forma
Release.spec.aggregateAggregate (el destino de despliegue de la Release)/aggregate/{publisher}/{name}
Release.spec.manifestManifest (el lockfile de mapeo de la Release)no es una posición URI — una ruta relativa, o el metadata.name simple de un Manifest junto a la Release
FeatureRecipe.spec.pipeline.<step>.pluginplugin Wasm/plugin/{pluginType}/{name}

Se enumeran tres posiciones porque los autores recurren a ellas esperando un URI, y no lo son. Un Manifest y una Release son documentos del lado del despliegue escritos uno junto al otro, no entidades indexadas en el catálogo, por lo que ni el extends: de uno ni el del otro, ni ningún manifest: de una Release, se resuelve contra el catálogo o un registro. El manifest: de una Release nombra un archivo, o el metadata.name simple de un Manifest situado junto a la Release. En las dos posiciones extends: el valor nombra un archivo, y una coordenada de registro escrita en cualquiera de ellas se rechaza, con la forma aceptada nombrada en el diagnóstico. Las dos posiciones extends: tampoco se escriben igual — un Manifest acepta también el metadata.name simple de un Manifest situado junto a la Release, mientras que una Release acepta la ruta relativa y nada más. Consulta entities/release.md para la forma de la Release y errors/fatal-halts.md para lo que dice cada rechazo.

La regla de inferencia: la posición en el esquema YAML determina el tipo de entidad. No hay ningún marcador en la superficie (sigilo, prefijo, anotación a nivel de esquema) que indique al autor a qué tipo de entidad hace referencia un campo type: concreto. Los autores tienen presentes las reglas basadas en la posición al leer YAML; las herramientas (el autocompletado del editor, aggrega inspect) leen las mismas reglas para ofrecer sugerencias específicas del tipo de entidad.

Dos formas de URI — plugins de coordenadas derivadas frente a entidades de catálogo con el tipo en los metadatos

Un URI de entidad de catálogo no lleva ningún sigilo de tipo (la sección anterior). Los URI de Plugin son el contrapunto deliberado: un URI de plugin sí escribe un segmento clasificador — su tipo de socket — directamente en la ruta. Las dos familias de referencias se leen de forma distinta a propósito, y saber a qué familia pertenece un URI te indica dónde buscar su clasificación.

Las coordenadas de Plugin se derivan del tipo del plugin. Una referencia de plugin es oci://hub.aggrega.ai/plugin/<pluginType>/<name>. La coordenada es derivada: el segmento <pluginType> y el <name> simple proceden del bloque de direccionamiento del plugin — metadata.pluginType y metadata.name — compuestos en la ruta. El socket no se codifica como ruta en el nombre; metadata.name es simple. La coordenada derivada ES la clave del registro (y del conjunto de plugins integrados), de modo que el registro organiza los plugins por socket. Los plugins básicos se resuelven en coordenadas como plugin/provider/helm, plugin/linter/publishing y plugin/parser/yaml — cada una la composición de un metadata.name simple (helm, publishing, yaml) con su metadata.pluginType (provider, linter, parser). El segmento <pluginType> es exactamente el tipo de socket del plugin: el mismo <name> simple bajo un pluginType distinto es un plugin distinto, porque la coordenada derivada — y por tanto la identidad — difiere. Para la taxonomía completa de sockets según la cual clasifica el segmento <pluginType>, consulta entities/plugin.md.

Las entidades de catálogo llevan el tipo en los metadatos. La referencia escrita es <publisher>/<category>/<name> (por ejemplo, core/datastore/postgres). El kind: de la entidad está en el archivo; el tipo de entidad del URI se infiere de la posición en el esquema, según Inferencia del tipo de entidad basada en la posición más arriba. La ruta se organiza por categoría, no por tipo: un Component lleva un segmento de categoría (core/datastore/postgres); una Recipe o una FeatureRecipe lleva su capacidad de renderizado como primer segmento (helm/postgres); los tipos restantes son planos, <publisher>/<name>. Nada en la ruta escribe el tipo de entidad.

Por qué difieren las dos formas. Los Plugins se organizan en el registro por socket, por lo que el segmento del socket es la clave natural del registro y está presente en todo URI de plugin. Las entidades de catálogo se organizan en el registro por categoría, por lo que lo que la ruta escribe es la categoría, no el tipo. Un URI te indica, por tanto, el socket de un plugin solo a partir de la ruta, pero el tipo de una entidad de catálogo solo después de leer el archivo (el tipo está en metadata; la posición lo aporta en un sitio de referencia). Esta asimetría es intencionada: la ruta de cada familia refleja cómo se organiza esa familia en el registro, no una única gramática uniforme impuesta a ambas.

Forma del URI — con versión frente a sin versión

Toda posición URI anterior acepta una referencia en una de tres formas — sin versión, o fijada tras dos puntos con una versión exacta o un rango con caret:

FormaEjemploSemántica
Sin versióncore/postgresSe resuelve en «cualquier versión» o en «la última registrada», según la semántica de resolución de la posición
Fijación exactacore/postgres:1.0.0Fija una versión concreta. La versión es una versión semántica, la forma que toma el metadata.version de cada entidad
Fijación con caretcore/postgres:^1.0.0Selecciona la versión más alta compatible con la indicada — para ^1.0.0, igual o superior a 1.0.0 e inferior a 2.0.0

La fijación es el texto que sigue a los últimos dos puntos de la referencia, y solo cuando ese texto no contiene ninguna /. Una referencia a un host de registro con puerto — localhost:5000/core/postgres — no lleva, por tanto, ninguna fijación: el texto tras los dos puntos del puerto continúa la referencia.

Una fijación que no tiene ninguna de estas formas — un caret cuyo texto no se lee como un rango de versiones (core/postgres:^garbage), o una fijación exacta que no es una versión semántica (core/postgres:1.x, core/postgres:1.0, core/postgres:v1.0.0) — no nombra ninguna versión. Cuando un comando resuelve una referencia así y esta no se resuelve, el rechazo nombra la referencia, la fijación y las tres formas anteriores, en lugar de informar de una entidad o una versión que el catálogo no contiene; el diagnóstico se describe en errors/fatal-halts.md bajo «A version pin is none of the forms a pin takes (Una fijación de versión no tiene ninguna de las formas que adopta una fijación)». La fijación solo se evalúa allí, de modo que una fijación mal formada nunca cambia qué referencias se resuelven, y una fijación bien formada que ninguna versión disponible satisface se notifica como tal. Ningún esquema establece la gramática de la fijación, por lo que una fijación mal formada se notifica cuando algo resuelve la referencia — aggrega validate, aggrega pull, aggrega build — y no cuando se carga el archivo.

Las formas coexisten en la misma posición. Los autores eligen según necesiten fijar la versión o flexibilidad de versión. El nivel mappings.{components,features}.type del Manifest admite ambas variantes como claves de diccionario distintas con la precedencia la clave con versión gana a la clave sin versión — una clave con versión (core/api-server:1.0.0) tiene precedencia sobre la clave sin versión (core/api-server) cuando ambas coinciden con la misma búsqueda. Las dos variantes no son excluyentes; ambas pueden estar en el mismo mapa type: y el resolvedor elige la más específica. El despacho del Provider se deriva del campo spec.capability de la Recipe resuelta, por lo que el Manifest asigna un tipo a una Recipe y nada más.

Para el régimen de consumo de versiones por entidad (qué entidades tienen realmente su campo de versión consumido por el despacho de resolución y cuáles lo usan como procedencia descriptiva), consulta vocabulary/inheritance-and-interface.md «Cross-entity version consumption (Consumo de versiones entre entidades)».

Una referencia a un Component, una Feature, un Aggregate o un Plugin también acepta un rango con caret (core/postgres:^1.0.0) y, sea cual sea su forma, selecciona la versión más alta que la satisface entre las que contiene el catálogo, mediante una única regla que aplica cada comando — consulta version-resolution.md. Para la coincidencia de tres formas de implements:, que es la comprobación de coherencia de un mapeo y no una selección, consulta 10-status.md «Version matching (Coincidencia de versiones)».

Identidad, no ubicación

Una referencia canónica a una entidad — incluida una referencia de plugin — es una identidad, no una ubicación: nombra qué es la entidad, nunca dónde reside actualmente.

La identidad es simple y sin host. No lleva ningún host de registro; el host es una coordenada de resolución que aporta la configuración mediante default_registry y que se vincula en el momento de la resolución. Trasladar un registro, o replicar la misma entidad en otro lugar, es un cambio de configuración — las referencias que nombran la entidad no se tocan.

La identidad también es sin versión. Una referencia puede llevar una fijación de versión opcional (:<version> o :^<version>) para restringir qué versiones la satisfacen, y cada Release registra la versión exacta resuelta como fijación en su lockfile, pero la versión se aporta junto a la identidad en lugar de quedar incorporada en ella.

En el momento de la resolución, el compilador une la identidad simple al host configurado y a la versión fijada para llegar a bytes concretos. Como ambos se aportan por separado, la misma referencia se resuelve contra un registro distinto o una versión fijada distinta sin ninguna edición en el código fuente que la nombra.

Inferencia de las formas abreviadas de URI OCI

Los autores no tienen que escribir cada URI como un URI OCI totalmente cualificado. El compilador aplica cuatro reglas de inferencia ortogonales para expandir las formas abreviadas de autoría en URI OCI canónicos en el momento de la resolución. Las reglas:

Regla 1 — Dominio predeterminado

A todo URI que carezca de dominio se le antepone el default_registry configurado en .aggrega-config.yaml (predeterminado: hub.aggrega.ai/).

# Shorthand
type: core/postgres:1.0.0
# Equivalent canonical form
type: hub.aggrega.ai/component/core/postgres:1.0.0

Regla 2 — Expansión contextual de la entidad

El compilador añade el segmento de tipo de entidad correcto según la posición en el esquema. La correspondencia es la misma que la de la tabla de inferencia por posición anterior (/component/, /aggregate/, /recipe/, /featurerecipe/, /feature/, /plugin/).

# Same string, two positions, two expansions
Aggregate.spec.components.foo.type: core/postgres:1.0.0
# → hub.aggrega.ai/component/core/postgres:1.0.0
Manifest.spec.mappings.components.type."core/postgres:1.0.0": helm/postgres:1.0.0
# Key: hub.aggrega.ai/component/core/postgres:1.0.0
# Value: hub.aggrega.ai/recipe/helm/postgres:1.0.0

Regla 3 — Precedencia en tres niveles

Antes de aplicar la inferencia OCI, el compilador resuelve el URI mediante el modelo de resolución de entidades en tres niveles documentado en architecture/13-catalog-and-registry.md:

  1. Ruta local — para los documentos que nombran una Release y su Manifest. El aggregate, el manifest o el extends de una Release, o el extends de un Manifest, escritos con un prefijo ./ o ../, se leen como un archivo relativo al directorio propio de la Release; la inferencia OCI no se ejecuta. Ninguna otra posición admite una ruta: un type, una clave o un valor de mapeo del Manifest, un implements o un plugin de pipeline escritos como ./… no nombran ninguna entidad y detienen el build. Una entidad escrita localmente se coloca bajo catalog/ en la raíz del espacio de trabajo o en un directorio que enumera workspace.catalog_dirs, y se resuelve por su nombre a través del nivel del espacio de trabajo y la caché.
  2. Espacio de trabajo y caché — la pila de búsqueda del catálogo del espacio de trabajo y, después, la caché. Los directorios catalog_dirs: del espacio de trabajo de .aggrega-config.yaml — o, para una Release a la que la configuración asigna directorios propios bajo workspace.releases, los de esa Release — se recorren en el orden escrito, y el directorio catalog/ de la raíz del espacio de trabajo se recorre en último lugar — después de cada entrada enumerada, y solo cuando ese directorio existe. Una coincidencia en cualquier punto de la pila cortocircuita la inferencia OCI. Un fallo consulta entonces artifact_cache_dir, que contiene lo que obtuvieron pulls anteriores del registro.
  3. Registro. Cuando el nivel del espacio de trabajo y la caché no encuentra nada, se aplican las reglas de inferencia OCI y la referencia se obtiene del registro remoto mediante aggrega pull, o mediante un build ejecutado con --auto-pull o con el ajuste auto_pull del espacio de trabajo; un build sin ninguno de los dos solo lee lo que fija su lockfile.

La cascada permite a un proyecto combinar los documentos que una Release nombra por ruta (el nivel de la ruta local) con contenido de catálogo copiado en el repositorio y local al espacio de trabajo (el nivel del espacio de trabajo y la caché) y contenido del registro obtenido de forma remota (el nivel del registro), y una referencia a una entidad se escribe igual sea cual sea el de los dos últimos niveles que contenga la entidad.

Cuando catalog_dirs: enumera más de un directorio, la lista es una pila de precedencia ordenada en la que gana el primero: una identidad de entidad presente en más de un directorio enumerado se resuelve en el directorio enumerado antes, y la aparición posterior queda oculta (reemplazada, no es un error) — así un proyecto puede colocar su propio directorio de catálogo por delante de uno compartido y reemplazar entidades por su identidad mientras el resto recae en el compartido. El reemplazo se informa en el detalle de la resolución. Dos archivos que reclaman la misma identidad dentro de un mismo directorio siguen siendo un error de autoría que detiene la carga.

El directorio catalog/ de la raíz del espacio de trabajo se sitúa al final de esa pila en lugar de al principio, de modo que todo lo que un proyecto enumera prevalece sobre él en caso de colisión, y enumerar un directorio no relacionado nunca impide que se lea. Se omite cuando una entrada enumerada ya lo alcanza — el recorrido de un directorio enumerado es recursivo, por lo que una pila que nombra la raíz del espacio de trabajo ya lo ha leído. Omitir catalog_dirs: y escribirlo como lista vacía son afirmaciones distintas: omitido, el espacio de trabajo sigue leyendo catalog/; escrito como [], no lee ningún catálogo local, que es como un espacio de trabajo indica que no tiene ninguno.

Regla 4 — Gestión de la versión

Un URI puede incluir u omitir el segmento de versión. La gestión de la versión depende de la posición de resolución (resolución del nivel del Manifest, coincidencia de implements:, importación de subagregados) según las reglas de consumo de versiones propias de la posición. Consulta inheritance-and-interface.md «Cross-entity version consumption (Consumo de versiones entre entidades)» para la semántica de versiones por entidad.

Inventario de cadenas de formato

Más allá de las cadenas URI, la superficie de autoría de Aggrega incluye varias convenciones distintas de cadenas de formato. Los autores que escriben o leen archivos YAML encuentran los siguientes formatos en distintas posiciones:

FormatoDónde se escribeValidado por
Plantilla de Go ({{ .field }})Recipe valuesMapping: / workload: / artifacts: / provides: / locals: / source:; FeatureRecipe injectMapping: / with: de pipeline; interpolación de parameters: en el Aggregate; Release directory: / subDirectory:Parser de plantillas de Go en el momento de la evaluación; reglas de disponibilidad por sitio en templates/expansion-matrix.md
Referencia de funciones de Sprig ({{ default 1 .v }}, etc.)Las mismas superficies que las plantillas de GoFuncMap de Sprig v3 registrado al inicializar el motor de plantillas; lista completa de helpers en templates/sprig-functions.md
JSON Schema 2020-12 (forma compacta o completa)Contenido schema: de Component / Feature (o un $ref: a una entrada de una SchemaLibrary)Validador de JSON Schema al cargar la entidad durante la resolución
JSON Pointer (RFC 6901)Claves locals.<*_path>: de la Recipe (volumes_path, containers_path, etc.); referencias a la salida de los pasos de pipeline: de la FeatureRecipe; cargas JSONPatch de los plugins WasmBase RFC 6901 según el contrato de los plugins Wasm; declarada en plugins/plugin-contract.md
Regex de SemVerCampos metadata.version en cada entidadRegex de JSON Schema ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-...)?$ por esquema de entidad
Fijación de versión (:<version>, :^<version>)El segmento de versión de una referencia a una entidad, en cada posición URI anteriorEl compilador, cuando resuelve la referencia: una fijación exacta es una versión semántica y el rango de una fijación con caret se analiza, y una fijación mal formada se rechaza con su propia condición — consulta Forma del URI más arriba
Ruta del sistema de archivosRutas relativas al catálogo (p. ej., las entradas catalog_dirs: de .aggrega-config.yaml); rutas de archivo $import: de la Recipe en workload: / artifacts: / valuesMapping:Se lee tal como está escrito en la resolución — una entrada catalog_dirs: relativa al archivo de configuración que la declara, una ruta $import: relativa al directorio propio de la entidad; no se expande ningún glob, de modo que un * nombra un archivo o directorio con ese nombre
Expresión de selector de etiquetasComponent.spec.usesSchema.<socket>.selector; appliesTo: / appliesToAnyOf: de la FeatureParser de selectores de Aggrega donde se evalúa el selector; gramática de selectores documentada en vocabulary/modifier-system.md
Forma de la clave de anotación (<namespace>/<name>)Claves metadata.annotations; claves features.annotations del Manifest; cascada de anotaciones del límiteRegex de JSON Schema por entidad; disciplina de prefijos reservados en vocabulary/labels-and-annotations.md
Nombre del Provider, opcionalmente con fijación de versión (helm, helm:^1.0.0)Recipe.spec.capability; FeatureRecipe.spec.capabilityBúsqueda de despacho del Provider; una fijación que ninguna versión de plugin satisface detiene el build
Clave de entrega de inject (env.<KEY>, file.<path>, arg.<flag>)Bloques inject: del Aggregate; salida de injectMapping: de la FeatureRecipeEsquema de inject en vocabulary/topology-triad.md

Cada formato tiene su propia gramática, su propio validador y su propia forma de informar de errores. Los autores que se topan con un error de análisis de una cadena de formato leen la referencia de cada formato para las reglas de sintaxis.

El editor informa de estos errores mientras escribes: aggrega serve valida cada documento que se le envía contra el esquema de su tipo y devuelve el mismo veredicto que daría un build (consulta cli/aggrega-serve.md «Live validation (Validación en vivo)»), y aggrega scaffold redacta un documento inicial de cualquier tipo.

Referencias cruzadas