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

Référence du langage

Le « quoi » et le « comment l’utiliser » d’Aggrega. Syntaxe, invocation de la CLI, catalogue d’erreurs, exemples détaillés.

Lisez les chapitres ci-dessous dans l’ordre pour une première compréhension. Les sous-répertoires de référence sont listés sous leur chapitre — allez-y directement lorsque vous cherchez une entité, un mot-clé, un provider, une commande de la CLI ou une erreur précis.

Avant de lire la suite des chapitres, consultez État du langage pour l’état actuel de maturité — quelles surfaces du langage sont disponibles aujourd’hui, lesquelles sont acceptées mais pas encore prises en compte par le compilateur, et lesquelles sont prévues pour des itérations futures. Compatibilité indique ce qu’une release promet pour les schémas, la ligne de commande, les outils de l’assistant, les codes d’erreur et les kits de plugin.

Modèle de niveaux des entités

Les types d’entités d’authoring d’Aggrega sont organisés en trois niveaux qui reflètent la progression de l’adoption (ci-dessous). À côté d’eux se trouve le Workload, propriété de la plateforme, qui n’est pas un type d’authoring à part entière — c’est la forme que prend l’entrée synthétisée d’une Recipe, et il exprime la forme de calcul au moyen du vocabulaire form: (stateless, stateful, daemon, scheduled, task, reference). Le découpage en niveaux est un mécanisme de documentation et d’intégration, pas une contrainte d’exécution : chaque type d’entité est un citoyen de première classe du langage ; le compilateur les traite de manière uniforme ; l’Aggrega open source prend en charge tous les niveaux sans licence ni restriction de fonctionnalités. Les marqueurs de niveau signalent « avancé ; à ignorer si inutile » pour la navigation, pas pour les capacités.

NiveauTypes d’entitésQuand les adopter
Niveau 1 — la surface minimale viableAggregate, Component, Recipe, Manifest, ReleaseJour 1 — les fondateurs solo et les petites équipes livrent des logiciels fonctionnels avec le seul Niveau 1. Le modèle mental : « J’ai une application ; je veux la déployer ; voici comment. »
Niveau 2 — séparation des rôlesFeature, FeatureRecipe, PluginJour 30 — les petites équipes où les rôles se séparent (développeur + Ops + parfois Sécurité). Le Niveau 2 arrive par les Plugins de rendu des providers (les Ops choisissent entre Helm, helm-chart, Compose, Terraform et CloudFormation), les Features (la Sécurité gère les identifiants séparément de la configuration de l’application) et les FeatureRecipes (personnalisation au moment de la liaison, par provider).
Niveau 3 — réutilisation transversale entre ComponentSchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibraryJour 365 — les catalogues matures où des formes communes reviennent dans de nombreuses entités. Le seuil est informel : lorsqu’une forme (par ex. PodResources) apparaît dans 5+ Components et que coordonner ses mises à jour devient une source de friction, une entrée de SchemaLibrary se justifie d’elle-même.

Chaque progression est facultative. Un fondateur solo n’est jamais obligé de regarder le Niveau 3 ; un catalogue d’entreprise a pleinement accès au Niveau 3 selon ses besoins. Le Niveau 1 est complet pour le cas d’usage du fondateur solo — un développeur peut livrer des applications fonctionnelles en utilisant uniquement des entités de Niveau 1. C’est une propriété de conception forte : le Niveau 1 n’est pas un « sous-ensemble qui compile » ; c’est un « sous-ensemble qui livre du logiciel ».

La surface de Niveau 1 à cinq entités a un coût d’entrée — Aggregate + Component + Recipe + Manifest + Release représente plus de cérémonie que « déposez un fichier YAML, obtenez un service en fonctionnement ». Ce coût est le prix de la séparation de l’authoring en quatre domaines (Intention du développeur / Catalogue de la plateforme / Exploitation de la plateforme / Routage) qui distingue Aggrega de Helm brut ou de Terraform brut. Les tutoriels de Niveau 1 détaillent explicitement la configuration à cinq entités.

Au sein du Niveau 3, le mécanisme spec.templates / $instantiate: (helpers paramétriques dans la SchemaLibrary) est documenté comme une sous-fonctionnalité encore plus avancée. La plupart des adoptants du Niveau 3 ne recourent pas d’emblée à spec.templates ; le seuil est « lorsque votre bibliothèque compte 6+ schémas partageant une structure paramétrée ».

Ordre de lecture

  1. Comment utiliser cette référence
  2. Conventions de nommage
  3. Vue d’ensemble de la référence des entités
  4. Vue d’ensemble du vocabulaire
  5. Vue d’ensemble des templates
  6. Vue d’ensemble des Providers
  7. Vue d’ensemble de la CLI
  8. Vue d’ensemble des erreurs
  9. Vue d’ensemble des exemples

Référence pour l’authoring de Plugin

La surface des plugins Wasm se situe à côté de la séquence des chapitres plutôt qu’à l’intérieur : un auteur de plugin la lit indépendamment du parcours d’authoring des entités. La page de l’entité plugin couvre la surface d’authoring du catalogue ; les pages ci-dessous couvrent les sockets, les payloads et le flux de travail de l’auteur.

  • plugin-contract — les sockets auxquels un plugin se rattache, leur place dans le pipeline et les formes d’entrée et de sortie de chaque socket.
  • plugin-developer-guide — le flux de travail complet de l’auteur : describe(), déclarations de capacités, limites d’exécution, le cycle de vie publish/pull/build, signature, gestion des versions.
  • policy-socket — le socket de gouvernance en détail : ses quatre rôles, les niveaux de gravité des verdicts, le canal d’entrée de l’opérateur et l’écriture d’une policy pour l’un ou l’autre des moteurs inclus dans le compilateur.
  • governance-attachment-facts — les faits par rattachement qu’une policy de gouvernance lit dans le graphe de build, y compris les trois unités du marquage de sensibilité et la raison pour laquelle un marquage absent ne vaut pas permission.
  • when-to-use-a-pipeline-step — choisir entre une étape de pipeline et une FeatureRecipe à base de templates.
  • embedded-plugins — les plugins inclus dans le binaire du compilateur.
  • tagging-plugins — les deux plugins de gouvernance intégrés qui écrivent des labels sans politique, governance/label-injector et governance/selector-tagger : leurs réglages et ce que chacun écrit.
  • core-importers — les dix importeurs du compilateur, de Langflow, Flowise et n8n à Compose, MCP et aux frameworks d’agents : ce que chacun lit et ébauche, leurs paramètres et leur publication avec chaque release du compilateur.
  • authoring-a-provider-walkthrough — un parcours détaillé de la rédaction d’un guest provider, d’un répertoire vide à un build qui écrit les fichiers dont le provider a effectué le rendu.
  • writing-a-governance-plugin — écrire votre propre plugin de gouvernance à partir du squelette d’adaptateur du kit de plugins : une règle, l’export de chaque rôle exécuté à la main, une entité Plugin dans le catalogue du workspace et un build qu’il refuse.
  • compatibility — comment les kits de plugin sont versionnés : ce qu’une release de correctif et une release mineure d’un kit peuvent changer, et ce qui permet à un plugin déjà construit de continuer à se charger.