Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Grammaire des URI et inventaire des chaînes de format

Les entités d’Aggrega se référencent mutuellement au moyen de chaînes URI qui apparaissent à plusieurs positions de rédaction distinctes. La même forme d’URI (core/postgres:1.0.0) apparaît dans cinq contextes de type d’entité ou plus, le compilateur déduisant le type d’entité de la position dans le schéma plutôt que d’un sigil ou d’un préfixe. Les auteurs qui lisent ou maintiennent un fichier YAML doivent garder à l’esprit les règles d’interprétation fondées sur la position pour savoir si core/postgres:1.0.0 désigne un type de Component, un module Aggregate, une Recipe, une FeatureRecipe ou un plugin Wasm.

Cette page regroupe la grammaire des URI pour toutes les positions, les règles de priorité pour les clés type: versionnées et non versionnées aux niveaux de mappage du Manifest, les règles d’inférence des formes abrégées d’URI OCI et l’inventaire plus large des chaînes de format dans l’ensemble du corpus (syntaxe des templates Go, fonctions Sprig, déclarations JSON Schema 2020-12, JSONPath, motifs glob, regex SemVer). Les auteurs qui ont besoin de savoir « que fait Aggrega de cette chaîne ? » devraient trouver la réponse ici.

Inférence du type d’entité fondée sur la position

La même chaîne URI porte un sens différent quant au type d’entité selon l’endroit où elle apparaît dans le schéma. Le tableau ci-dessous énumère chaque position où Aggrega attend un URI de référence d’entité, avec le type d’entité déduit :

PositionType d’entité déduitExpansion du chemin OCI
Aggregate.spec.components.<id>.typeComponent/component/{publisher}/{category}/{name}
Aggregate.spec.subsystems.<name>.components.<id>.typeComponent (comme pour components — les sous-systèmes sont un regroupement de composants)/component/{publisher}/{category}/{name}
Aggregate.spec.aggregates.<id>.typeAggregate (module sous-agrégat)/aggregate/{publisher}/{name}
Aggregate.spec.components.<id>.features.<id>.typeFeature/feature/{publisher}/{name}
Aggregate.spec.components.<id>.features.<id>.typeFeature (identifiant — avec le label feature.aggrega.ai/kind: secret)/feature/{publisher}/{name}
Manifest.spec.mappings.components.type.<key>Component (l’URI utilisé comme clé de recherche) ; la valeur est un URI de Recipeclé : /component/ ; valeur : /recipe/{provider}/{name}
Manifest.spec.mappings.components.name.<id>Recipe (liaison de surcharge granulaire)/recipe/{provider}/{name}
Manifest.spec.mappings.features.type.<key>Feature (clé de recherche) ; la valeur est un URI de FeatureRecipeclé : /feature/ ; valeur : /featurerecipe/{provider}/{name}
Manifest.spec.mappings.features.name.<id>FeatureRecipe (liaison de surcharge granulaire)/featurerecipe/{provider}/{name}
Manifest.spec.mappings.features.annotations.<key>.featureFeature (liée à une annotation)/feature/{publisher}/{name}
Recipe.spec.implementsComponent (contrat d’interface)/component/{publisher}/{category}/{name}
FeatureRecipe.spec.implementsFeature (contrat d’interface)/feature/{publisher}/{name}
Component.spec.extends / Feature.spec.extendsComponent / Feature (parent dans la chaîne d’héritage)/component/{publisher}/{category}/{name} ou /feature/{publisher}/{name}
Manifest.spec.extendsManifest (parent dans la chaîne d’héritage des mappages)pas une position URI — un chemin relatif, ou le simple metadata.name d’un Manifest à côté de la Release
Release.spec.extendsRelease (parent dans la chaîne d’héritage)pas une position URI — un chemin relatif vers un fichier de Release, et aucune autre forme
Release.spec.aggregateAggregate (la cible de déploiement de la Release)/aggregate/{publisher}/{name}
Release.spec.manifestManifest (le lockfile de mappage de la Release)pas une position URI — un chemin relatif, ou le simple metadata.name d’un Manifest à côté de la Release
FeatureRecipe.spec.pipeline.<step>.pluginplugin Wasm/plugin/{pluginType}/{name}

Trois positions sont listées parce que les auteurs s’en servent en s’attendant à un URI, et elles n’en sont pas un. Un Manifest et une Release sont des documents côté déploiement rédigés l’un à côté de l’autre plutôt que des entités indexées dans le catalogue, de sorte que ni l’extends: de l’un ni celui de l’autre, ni aucun manifest: d’une Release, n’est résolu par rapport au catalogue ou à un registre. Le manifest: d’une Release nomme un fichier, ou le simple metadata.name d’un Manifest placé à côté de la Release. Aux deux positions extends:, la valeur nomme un fichier, et une coordonnée de registre écrite à l’une ou l’autre est refusée, la forme acceptée étant nommée dans le diagnostic. Les deux positions extends: ne s’écrivent pas non plus de la même façon — un Manifest accepte aussi le simple metadata.name d’un Manifest placé à côté de la Release, tandis qu’une Release accepte le chemin relatif et rien d’autre. Voir entities/release.md pour la forme de la Release et errors/fatal-halts.md pour ce que dit chaque refus.

La règle d’inférence : la position dans le schéma YAML détermine le type d’entité. Aucun marqueur de surface (sigil, préfixe, annotation au niveau du schéma) n’indique à l’auteur quel type d’entité référence un champ type: donné. Les auteurs gardent à l’esprit les règles fondées sur la position en lisant du YAML ; l’outillage (la complétion de l’éditeur, aggrega inspect) lit les mêmes règles pour proposer des suggestions propres au type d’entité.

Deux formes d’URI — plugins à coordonnées dérivées face aux entités de catalogue typées par leurs métadonnées

Un URI d’entité de catalogue ne porte aucun sigil de type (la section précédente). Les URI de Plugin sont le contrepoint délibéré : un URI de plugin écrit bel et bien un segment de classification — son type de socket — directement dans le chemin. Les deux familles de références se lisent différemment à dessein, et savoir à quelle famille appartient un URI vous indique où chercher sa classification.

Les coordonnées de Plugin sont dérivées du type du plugin. Une référence de plugin est oci://hub.aggrega.ai/plugin/<pluginType>/<name>. La coordonnée est dérivée : le segment <pluginType> et le simple <name> proviennent du bloc d’adressage du plugin — metadata.pluginType et metadata.name — composés dans le chemin. Le socket n’est pas encodé sous forme de chemin dans le nom ; metadata.name est simple. La coordonnée dérivée EST la clé du registre (et de l’ensemble des plugins embarqués), de sorte que le registre organise les plugins par socket. Les plugins de base se résolvent en coordonnées telles que plugin/provider/helm, plugin/linter/publishing et plugin/parser/yaml — chacune étant la composition d’un simple metadata.name (helm, publishing, yaml) avec son metadata.pluginType (provider, linter, parser). Le segment <pluginType> est exactement le type de socket du plugin : le même simple <name> sous un autre pluginType est un autre plugin, car la coordonnée dérivée — et donc l’identité — diffère. Pour la taxonomie complète des sockets selon laquelle le segment <pluginType> classe, voir entities/plugin.md.

Les entités de catalogue portent le type dans les métadonnées. La référence rédigée est <publisher>/<category>/<name> (par exemple, core/datastore/postgres). Le kind: de l’entité se trouve dans le fichier ; le type d’entité de l’URI est déduit de la position dans le schéma, selon Inférence du type d’entité fondée sur la position ci-dessus. Le chemin s’organise par catégorie, non par type : un Component porte un segment de catégorie (core/datastore/postgres) ; une Recipe ou une FeatureRecipe porte sa capacité de rendu comme premier segment (helm/postgres) ; les types restants sont plats, <publisher>/<name>. Rien dans le chemin n’écrit le type d’entité.

Pourquoi les deux formes diffèrent. Les Plugins sont organisés dans le registre par socket, de sorte que le segment de socket est la clé naturelle du registre et figure dans chaque URI de plugin. Les entités de catalogue sont organisées dans le registre par catégorie, de sorte que c’est la catégorie — et non le type — que le chemin écrit. Un URI vous indique donc le socket d’un plugin à partir du seul chemin, mais ne vous indique le type d’une entité de catalogue qu’après lecture du fichier (le type se trouve dans metadata, la position le fournit à un site de référence). Cette asymétrie est intentionnelle : le chemin de chaque famille reflète la façon dont cette famille est organisée dans le registre, et non une grammaire unique et uniforme imposée aux deux.

Forme de l’URI — versionné ou non versionné

Chaque position URI ci-dessus accepte une référence sous l’une de trois formes — non versionnée, ou épinglée après deux-points avec une version exacte ou une plage avec caret :

FormeExempleSémantique
Sans versioncore/postgresSe résout en « n’importe quelle version » ou en « dernière enregistrée », selon la sémantique de résolution de la position
Épinglage exactcore/postgres:1.0.0Épingle une version précise. La version est une version sémantique, la forme que prend le metadata.version de chaque entité
Épinglage avec caretcore/postgres:^1.0.0Sélectionne la version la plus élevée compatible avec celle nommée — pour ^1.0.0, supérieure ou égale à 1.0.0 et inférieure à 2.0.0

L’épinglage est le texte qui suit le dernier deux-points de la référence, et seulement lorsque ce texte ne contient aucun /. Une référence à un hôte de registre avec un port — localhost:5000/core/postgres — ne porte donc aucun épinglage : le texte qui suit le deux-points du port prolonge la référence.

Un épinglage qui ne prend aucune de ces formes — un caret dont le texte ne se lit pas comme une plage de versions (core/postgres:^garbage), ou un épinglage exact qui n’est pas une version sémantique (core/postgres:1.x, core/postgres:1.0, core/postgres:v1.0.0) — ne nomme aucune version. Lorsqu’une commande résout une telle référence et que celle-ci ne se résout pas, le refus nomme la référence, l’épinglage et les trois formes ci-dessus, plutôt que de signaler une entité ou une version que le catalogue ne contient pas ; le diagnostic est décrit dans errors/fatal-halts.md sous « A version pin is none of the forms a pin takes (Un épinglage de version ne prend aucune des formes d’un épinglage) ». L’épinglage n’est jugé qu’à cet endroit, de sorte qu’un épinglage mal formé ne change jamais quelles références se résolvent, et qu’un épinglage bien formé qu’aucune version disponible ne satisfait est signalé comme tel. Aucun schéma n’énonce la grammaire de l’épinglage, de sorte qu’un épinglage mal formé est signalé lorsque quelque chose résout la référence — aggrega validate, aggrega pull, aggrega build — et non lorsque le fichier se charge.

Les formes coexistent dans la même position. Les auteurs choisissent selon qu’ils ont besoin d’épingler la version ou de souplesse de version. Le niveau mappings.{components,features}.type du Manifest prend en charge les deux variantes comme clés de dictionnaire distinctes, avec la précédence la clé versionnée l’emporte sur la non versionnée — une clé versionnée (core/api-server:1.0.0) a la précédence sur la clé non versionnée (core/api-server) lorsque les deux correspondent à la même recherche. Les deux variantes ne s’excluent pas ; les deux peuvent figurer dans la même map type: et le résolveur choisit la plus spécifique. Le dispatch du Provider découle du champ spec.capability de la Recipe résolue, de sorte que le Manifest associe un type à une Recipe et rien de plus.

Pour le régime de consommation des versions par entité (quelles entités voient réellement leur champ de version consommé par le dispatch de résolution, et lesquelles ne s’en servent que comme provenance descriptive), voir vocabulary/inheritance-and-interface.md « Cross-entity version consumption (Consommation des versions entre entités) ».

Une référence à un Component, une Feature, un Aggregate ou un Plugin accepte aussi une plage avec caret (core/postgres:^1.0.0) et, quelle que soit sa forme, elle sélectionne la version satisfaisante la plus élevée parmi celles que le catalogue contient, selon une règle unique que chaque commande applique — voir version-resolution.md. Pour la correspondance à trois formes de implements:, qui est le contrôle de cohérence d’un mappage plutôt qu’une sélection, voir 10-status.md « Version matching (Correspondance des versions) ».

Identité, pas emplacement

Une référence canonique à une entité — y compris une référence de plugin — est une identité, pas un emplacement : elle nomme ce que l’entité est, jamais où elle se trouve actuellement.

L’identité est simple et sans hôte. Elle ne porte aucun hôte de registre ; l’hôte est une coordonnée de résolution fournie par la configuration via default_registry et liée au moment de la résolution. Déplacer un registre, ou répliquer la même entité ailleurs, est un changement de configuration — les références qui nomment l’entité restent intactes.

L’identité est aussi sans version. Une référence peut porter un épinglage de version facultatif (:<version> ou :^<version>) pour restreindre les versions qui la satisfont, et chaque Release enregistre la version exacte résolue comme épinglage dans son lockfile, mais la version est fournie à côté de l’identité plutôt qu’intégrée à celle-ci.

Au moment de la résolution, le compilateur joint l’identité simple à l’hôte configuré et à la version épinglée pour aboutir à des octets concrets. Comme les deux sont fournis séparément, la même référence se résout par rapport à un autre registre ou à une autre version épinglée sans aucune modification de la source qui la nomme.

Inférence des formes abrégées d’URI OCI

Les auteurs n’ont pas à écrire chaque URI sous la forme d’un URI OCI pleinement qualifié. Le compilateur applique quatre règles d’inférence orthogonales pour développer les formes abrégées de rédaction en URI OCI canoniques au moment de la résolution. Les règles :

Règle 1 — Domaine par défaut

Tout URI dépourvu de domaine est préfixé par le default_registry configuré dans .aggrega-config.yaml (par défaut : hub.aggrega.ai/).

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

Règle 2 — Expansion contextuelle de l’entité

Le compilateur ajoute le segment de type d’entité correct en fonction de la position dans le schéma. Le mappage est le même que dans le tableau d’inférence par position ci-dessus (/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

Règle 3 — Précédence à trois niveaux

Avant d’appliquer l’inférence OCI, le compilateur résout l’URI au moyen du modèle de résolution des entités à trois niveaux documenté dans architecture/13-catalog-and-registry.md :

  1. Chemin local — pour les documents qu’une Release et son Manifest nomment. L’aggregate, le manifest ou l’extends d’une Release, ou l’extends d’un Manifest, écrits avec un préfixe ./ ou ../, sont lus comme un fichier relatif au propre répertoire de la Release ; l’inférence OCI ne s’exécute pas. Aucune autre position n’accepte de chemin : un type, une clé ou une valeur de mappage du Manifest, un implements ou un plugin de pipeline écrits sous la forme ./… ne nomment aucune entité et arrêtent le build. Une entité rédigée localement est placée sous catalog/ à la racine de l’espace de travail ou dans un répertoire que liste workspace.catalog_dirs, et se résout par son nom à travers le niveau de l’espace de travail et du cache.
  2. Espace de travail et cache — la pile de recherche du catalogue de l’espace de travail, puis le cache. Les répertoires catalog_dirs: de l’espace de travail de .aggrega-config.yaml — ou, pour une Release à laquelle la configuration attribue ses propres répertoires sous workspace.releases, ceux de cette Release — sont parcourus dans l’ordre où ils sont écrits, et le répertoire catalog/ de la racine de l’espace de travail est parcouru en dernier — après chaque entrée listée, et seulement lorsque ce répertoire existe. Une correspondance n’importe où dans la pile court-circuite l’inférence OCI. Un échec consulte ensuite artifact_cache_dir, qui contient ce que les précédents pulls depuis le registre ont récupéré.
  3. Registre. Lorsque le niveau de l’espace de travail et du cache ne trouve rien, les règles d’inférence OCI s’appliquent et la référence est récupérée depuis le registre distant par aggrega pull, ou par un build exécuté avec --auto-pull ou le paramètre auto_pull de l’espace de travail ; un build sans l’un ni l’autre ne lit que ce que son lockfile épingle.

La cascade permet à un projet de combiner les documents qu’une Release nomme par chemin (le niveau du chemin local) avec le contenu de catalogue copié dans le dépôt et local à l’espace de travail (le niveau de l’espace de travail et du cache) et le contenu du registre récupéré à distance (le niveau du registre), et une référence d’entité s’écrit de la même façon quel que soit celui des deux derniers niveaux qui contient l’entité.

Lorsque catalog_dirs: liste plus d’un répertoire, la liste est une pile de précédence ordonnée où le premier l’emporte : une identité d’entité présente dans plusieurs répertoires listés se résout vers le répertoire listé en premier, et l’occurrence suivante est masquée (remplacée, pas une erreur) — un projet peut ainsi placer son propre répertoire de catalogue devant un répertoire partagé et remplacer des entités par leur identité, tandis que les autres retombent sur celui-ci. Le remplacement est indiqué dans le détail de la résolution. Deux fichiers revendiquant la même identité au sein d’un même répertoire restent une erreur de rédaction qui arrête le chargement.

Le répertoire catalog/ de la racine de l’espace de travail se trouve à la fin de cette pile plutôt qu’en tête, de sorte que tout ce qu’un projet liste l’emporte sur lui en cas de collision, et lister un répertoire sans rapport n’empêche jamais qu’il soit lu. Il est ignoré lorsqu’une entrée listée l’atteint déjà — le parcours d’un répertoire listé est récursif, donc une pile qui nomme la racine de l’espace de travail l’a déjà lu. Omettre catalog_dirs: et l’écrire comme liste vide sont deux déclarations différentes : omis, l’espace de travail lit quand même catalog/ ; écrit [], il ne lit aucun catalogue local, et c’est ainsi qu’un espace de travail indique qu’il n’en a pas.

Règle 4 — Gestion de la version

Un URI peut inclure ou omettre le segment de version. La gestion de la version dépend de la position de résolution (résolution du niveau du Manifest, correspondance implements:, import de sous-agrégats) selon les règles de consommation des versions propres à la position. Voir inheritance-and-interface.md « Cross-entity version consumption (Consommation des versions entre entités) » pour la sémantique des versions par entité.

Inventaire des chaînes de format

Au-delà des chaînes URI, la surface de rédaction d’Aggrega comporte plusieurs conventions distinctes de chaînes de format. Les auteurs qui écrivent ou lisent des fichiers YAML rencontrent les formats suivants à différentes positions :

FormatLieu de rédactionValidé par
Template Go ({{ .field }})Recipe valuesMapping: / workload: / artifacts: / provides: / locals: / source: ; FeatureRecipe injectMapping: / with: de pipeline ; interpolation de parameters: dans l’Aggregate ; Release directory: / subDirectory:Parser de templates Go au moment de l’évaluation ; règles de disponibilité par site dans templates/expansion-matrix.md
Référence des fonctions Sprig ({{ default 1 .v }} etc.)Mêmes surfaces que les templates GoFuncMap de Sprig v3 enregistrée à l’initialisation du moteur de templates ; liste complète des helpers dans templates/sprig-functions.md
JSON Schema 2020-12 (forme compacte ou complète)Contenu schema: d’un Component / d’une Feature (ou un $ref: vers une entrée d’une SchemaLibrary)Validateur JSON Schema au chargement de l’entité pendant la résolution
JSON Pointer (RFC 6901)Clés locals.<*_path>: de la Recipe (volumes_path, containers_path, etc.) ; références aux sorties des étapes de pipeline: de la FeatureRecipe ; charges utiles JSONPatch des plugins WasmBase RFC 6901 selon le contrat des plugins Wasm ; déclarée dans plugins/plugin-contract.md
Regex SemVerChamps metadata.version sur chaque entitéRegex JSON Schema ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-...)?$ par schéma d’entité
Épinglage de version (:<version>, :^<version>)Le segment de version d’une référence d’entité, à chaque position URI ci-dessusLe compilateur, lorsqu’il résout la référence : un épinglage exact est une version sémantique et la plage d’un épinglage avec caret s’analyse, et un épinglage mal formé est refusé sous sa propre condition — voir Forme de l’URI ci-dessus
Chemin du système de fichiersChemins relatifs au catalogue (par ex. les entrées catalog_dirs: de .aggrega-config.yaml) ; chemins de fichiers $import: de la Recipe dans workload: / artifacts: / valuesMapping:Lu tel qu’écrit lors de la résolution — une entrée catalog_dirs: relative au fichier de configuration qui la déclare, un chemin $import: relatif au propre répertoire de l’entité ; aucun glob n’est développé, donc un * nomme un fichier ou un répertoire de ce nom
Expression de sélecteur de labelsComponent.spec.usesSchema.<socket>.selector ; appliesTo: / appliesToAnyOf: de la FeatureParser de sélecteurs d’Aggrega là où le sélecteur est évalué ; grammaire des sélecteurs documentée dans vocabulary/modifier-system.md
Forme de clé d’annotation (<namespace>/<name>)Clés metadata.annotations ; clés features.annotations du Manifest ; cascade des annotations de la frontièreRegex JSON Schema par entité ; discipline des préfixes réservés dans vocabulary/labels-and-annotations.md
Nom du Provider, éventuellement épinglé à une version (helm, helm:^1.0.0)Recipe.spec.capability; FeatureRecipe.spec.capabilityRecherche de dispatch du Provider ; un épinglage qu’aucune version de plugin ne satisfait arrête le build
Clé de livraison d’inject (env.<KEY>, file.<path>, arg.<flag>)Blocs inject: de l’Aggregate ; sortie injectMapping: de la FeatureRecipeSchéma d’inject dans vocabulary/topology-triad.md

Chaque format a sa propre grammaire, son propre validateur et sa propre forme de signalement des erreurs. Les auteurs qui rencontrent une erreur d’analyse d’une chaîne de format lisent la référence propre au format pour les règles de syntaxe.

L’éditeur signale ces erreurs pendant que vous rédigez : aggrega serve valide chaque document qu’on lui envoie par rapport au schéma de son type et renvoie le même verdict qu’un build donnerait (voir cli/aggrega-serve.md « Live validation (Validation en direct) »), et aggrega scaffold ébauche un document de départ de n’importe quel type.

Références croisées