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

Fonctions et helpers Sprig

Le moteur de templates d’Aggrega branche la bibliothèque de fonctions Sprig v3 ainsi que les helpers propres d’Aggrega (optional et capitalizedWords) dans chaque template Go que le moteur de rendu évalue, et remplace la fonction index de Go par une fonction qui s’arrête sur une clé que la map ne contient pas. Les auteurs qui écrivent le valuesMapping: d’une Recipe, l’injectMapping: d’une FeatureRecipe ou toute autre surface de template que le moteur de rendu évalue disposent de l’ensemble complet des helpers Sprig, à côté des fonctions intégrées de text/template de Go et des champs du contexte d’exécution documentés dans template-context-contract.md.

🔴 Lisez « que le moteur de rendu évalue » comme la portée qu’il désigne, car une surface d’écriture se situe en dehors. Une coordonnée source: structurée est résolue afin que l’artefact qu’elle nomme puisse être épinglé, et cette résolution n’est pas une passe de rendu : elle enregistre les helpers propres d’Aggrega et rien d’autre, donc un appel Sprig dans un champ source:, ou dans une entrée locals: qu’il lit, arrête le pull. Une entrée qu’aucun champ source: ne lit est évaluée par le rendu seul, avec l’ensemble complet. Résoudre une coordonnée fixe ce qui est épinglé plutôt que de produire un artefact, ce qui explique pourquoi son ensemble de fonctions est délibérément plus restreint — voir errors/fatal-halts.md « Resolving a source: coordinate registers a narrower function set (La résolution d’une coordonnée source enregistre un ensemble de fonctions plus restreint) » pour l’arrêt et la forme portable à utiliser à la place.

L’ensemble Sprig est enregistré seul pour l’interpolation des paramètres, et avec les helpers propres d’Aggrega sur les surfaces de template de valeur du moteur de rendu.

Ce qui est branché

Sprig v3 expose l’ensemble de sa surface de helpers — environ 200 fonctions réparties dans les catégories ci-dessous. Cette page esquisse les catégories avec les helpers courants de chacune ; la référence canonique par fonction est la documentation amont de Sprig.

  • Chaînes — upper, lower, title, trim, trimAll, trimPrefix, trimSuffix, replace, contains, hasPrefix, hasSuffix, substr, quote, squote, cat, indent, nindent, repeat, helpers de casse (snakecase, camelcase, kebabcase), helpers d’abréviation (abbrev, abbrevboth, trunc), helpers de somme de contrôle (sha1sum, sha256sum, sha512sum, adler32sum), toString.
  • Listes — list, tuple, first, last, rest, initial, append/push, prepend, concat, reverse, uniq, without, has, slice, chunk, join, splitList, split, splitn, sortAlpha, compact.
  • Dictionnaires — dict, get, set, unset, hasKey, keys, values, pick, omit, pluck, merge, mergeOverwrite, dig, deepCopy.
  • Mathématiques — add, sub, mul, div, mod, add1, min, max, ceil, floor, round, plus les variantes décimales suffixées par f (addf, subf, mulf, divf, minf, maxf).
  • Conversion — int, int64, float64, atoi, toString, toDecimal, seq, until, untilStep.
  • Encodage — b64enc, b64dec, b32enc, b32dec, toJson, toPrettyJson, toRawJson, fromJson, plus les variantes JSON préfixées par must qui font remonter les erreurs de décodage au lieu de mettre silencieusement à zéro.
  • Vérifications de type — typeOf, typeIs, typeIsLike, kindOf, kindIs, deepEqual, empty.
  • Valeurs par défaut et flux — default, coalesce, all, any, ternary, fail (lève une erreur de template avec un message personnalisé — la manière canonique d’interrompre un rendu avec un message de garde).
  • Regex — regexMatch, regexFind, regexFindAll, regexReplaceAll, regexReplaceAllLiteral, regexSplit, regexQuoteMeta, plus les variantes strictes préfixées par must.
  • Chemins — base, dir, clean, ext, isAbs (style Unix) ; osBase, osClean, osDir, osExt, osIsAbs (selon le système d’exploitation).
  • SemVer — semver, semverCompare.
  • URL — urlParse, urlJoin.
  • Dates — ago, date, dateInZone, dateModify, duration, durationRound, htmlDate, htmlDateInZone, now, toDate, unixEpoch.

Mise en garde sur le déterminisme

Aggrega garantit une sortie identique octet pour octet pour une entrée identique octet pour octet. Un sous-ensemble des helpers Sprig lit l’état ambiant et rompt cette garantie lorsqu’il est invoqué depuis un template. Les auteurs devraient éviter les helpers suivants dans les surfaces de template qui contribuent aux artefacts rendus :

  • Lecteurs de l’horloge système — now, date, dateInZone, dateModify, htmlDate, htmlDateInZone, ago lorsqu’il est appelé sans heure de référence figée.
  • Générateurs aléatoires — randAlpha, randAlphaNum, randAscii, randNumeric, randBytes, randInt, uuidv4.
  • Lecteurs d’environnement — env, expandenv (lisent les variables d’environnement du processus, qui diffèrent d’un poste de travail d’opérateur à l’autre et d’un runner CI à l’autre).
  • Résolveurs réseau — getHostByName.

Ces helpers ne sont pas bloqués par le moteur ; ils font partie de l’ensemble Sprig v3. La discipline consistant à les éviter dans les templates du chemin de rendu est maintenue par les relecteurs et par la garantie de sortie déterministe sur laquelle s’appuient les auteurs et le catalogue de la bibliothèque standard.

Nombres dans un template de valeur

Un nombre qu’un auteur écrit atteint un template de valeur en tant que nombre. Un nombre sans partie décimale est un entier et s’affiche entier : 1000000 affiche 1000000. Tout autre nombre s’affiche sous sa forme décimale exacte la plus courte, jamais en notation exponentielle : un 0.0000001 écrit par l’auteur affiche 0.0000001 et un 1e21 écrit par l’auteur affiche 1000000000000000000000, que le template écrive la valeur directement ou la convertisse en texte avec toString, quote, printf "%v" ou toJson. Un nombre que renvoie une fonction mathématique — mulf, float64, round et leurs semblables — est la valeur propre de cette fonction et s’affiche sous la forme propre à cette fonction, qui est la notation exponentielle pour une valeur très petite ou très grande : {{ mulf .values.ratio 1 }} affiche 1e-07 pour un 0.0000001 écrit par l’auteur.

Les comparaisons — eq, ne, lt, le, gt et ge — lisent deux nombres par leur valeur, quel que soit le type qui porte chacun, de sorte qu’un entier écrit par l’auteur se compare à un décimal écrit dans le template, et 3 est égal à 3.0 :

{{ lt .values.replicas 1.5 }} # .values.replicas = 1 → true
{{ eq .values.replicas 3.0 }} # .values.replicas = 3 → true

Un nombre n’est jamais comparé à du texte : chacune des six, lorsqu’elle reçoit un nombre et un texte entre guillemets, arrête le build en nommant les deux types. Comparez le nombre à un nombre écrit sans guillemets, ou convertissez-le d’abord en texte :

{{ eq .values.port "8080" }} # halts: cannot compare a number with text
{{ eq .values.port 8080 }} # .values.port = 8080 → true
{{ eq (toString .values.port) "8080" }} # .values.port = 8080 → true

L’arrêt est A value template failed while it ran (Un template de valeur a échoué pendant son exécution). Une assertion lit un nombre écrit par l’auteur de la même manière ; voir Nombres sur cette surface.

Présence et vacuité — deux questions différentes

Un template pose l’une de deux questions sur une valeur, et chaque question a ses propres helpers.

  • L’auteur l’a-t-il écrite ? hasKey et optional répondent selon la présence. Une clé que l’auteur a écrite est présente quel que soit son contenu — 0, "" et false compris — et seule une clé que l’auteur a omise est absente.
  • Est-elle vide ? default, with, if et empty répondent selon la vacuité. 0, "", false, une liste vide, une map vide et une valeur absente comptent tous comme vides dans ce cas, comme dans Helm.
.values.replicashasKey .values "replicas"optional .values "replicas" 1.values.replicas | default 1if .values.replicas
absentfalse11false
0true01false
3true33true

Une valeur qui peut légitimement valoir 0, "" ou false — un nombre de réplicas de zéro, un délai d’expiration de zéro, un indicateur désactivé — se teste avec hasKey ou optional, de sorte que le 0 de l’auteur atteint la sortie en tant que 0. default, with et if conviennent à une valeur dont la forme vide n’a pas de signification propre, où « vide » et « non écrit » peuvent être traités de la même façon. Lisez une clé donnée d’une seule manière par template : une clé que le template lit aussi comme chemin pointé compte comme présente, comme le décrit la limite de optional.

Helpers spécifiques à Aggrega

optional — valeur de repli sensible à la présence

optional <map> <key> <fallback> renvoie la valeur à <key> dans <map> si la clé est présente, sinon renvoie <fallback>. Contrairement au default de Sprig, optional distingue « clé absente » de « clé présente avec une valeur zéro, vide ou fausse ».

La signature prend la map et la clé comme arguments distincts parce qu’une valeur passée par l’opérateur | d’un template Go a perdu l’accès à sa map parente. Sans la map parente dans la portée, la présence ne peut pas être vérifiée.

Une limite à la vérification de présence, et elle vient du template plutôt que du helper : un template de valeur lit une clé absente comme rien, ce qu’il fait en fournissant une valeur vide à chaque clé absente que le template nomme comme chemin pointé et lit comme valeur. Ainsi, un template qui lit une clé à la fois via optional et comme un tel chemin trouve cette clé présente et vide, et obtient la valeur vide plutôt que la valeur de repli. Lisez une clé d’une seule manière par template et les deux réponses concordent.

# Present and non-zero: returns 3
{{ optional .infra `replicas` 1 }} # .infra.replicas = 3 → 3
# Absent: returns the fallback
{{ optional .infra `replicas` 1 }} # .infra.replicas unset → 1
# Present but authored zero: returns 0 (the discriminator)
{{ optional .infra `replicas` 1 }} # .infra.replicas = 0 → 0

Le dernier cas est la distinction que le default de Sprig ne peut pas faire. {{ .infra.replicas | default 1 }} renvoie 1 que replicas ait été écrit comme 0 ou omis — la confusion qui empêche les patterns légitimes de scale-to-zero, sans nouvelle tentative, sans délai d’expiration et d’indicateur à faux.

Convention de citation des clés : préférer les backticks. Les templates Go acceptent pour l’argument de clé aussi bien les littéraux de chaîne entre guillemets doubles ("replicas") qu’entre backticks (`replicas`) ; les deux produisent la même chaîne au moment de l’évaluation du template. Les exemples du catalogue et de la documentation utilisent uniformément la forme avec backticks parce qu’elle est sûre pour YAML dans tout contexte de citation. Une clé entre guillemets doubles à l’intérieur d’un scalaire YAML entre guillemets doubles termine la chaîne YAML au milieu du template :

# BROKEN — the inner " closes the outer YAML string:
service_port: "{{ optional .infra "port" 8080 }}"
# WORKS — backticks are not a YAML escape character:
service_port: "{{ optional .infra `port` 8080 }}"

Lorsque le template se trouve dans un scalaire de bloc YAML (forme |) ou en tant que scalaire à valeur nue, les deux formes sont rendues correctement. Lorsque le template est intégré dans un scalaire YAML entre guillemets doubles (le pattern field: "{{ ... }}" de la valeur de champ en tant que template), les backticks sont obligatoires. La convention unique (toujours des backticks) évite entièrement le piège de la citation YAML.

Quand préférer optional à default. Utilisez optional lorsque le champ peut légitimement être zéro, vide ou faux et que l’auteur du catalogue doit distinguer « l’auteur ne l’a pas défini » de « l’auteur l’a défini à une valeur falsy ». Utilisez default lorsque la confusion est acceptable (p. ex. des champs de chaîne où le vide n’est pas valide ; des champs numériques où zéro n’est pas valide).

Disponibilité par surface. optional est enregistré sur chaque surface que le moteur de rendu évalue : les surfaces de template de valeur (valuesMapping de la Recipe, injectMapping de la FeatureRecipe, provides, pipeline.with, le corps du Workload), l’évaluateur d’assertions et les templates de chemin (directory: / subDirectory: sur les frontières de la Release). Ce qui diffère sur la surface des templates de chemin n’est pas l’ensemble de helpers mais la politique des clés manquantes : un template de chemin traite une clé absente comme une erreur plutôt que comme vide, parce qu’un segment de chemin silencieusement vide produit une arborescence de système de fichiers cassée qui n’est découverte qu’après le build. optional lit une clé sans que cette politique stricte se déclenche d’abord, et c’est ce qui le rend utilisable à cet endroit.

capitalizedWords — réduire un nom à des lettres et des chiffres

capitalizedWords <string> lit son argument comme des mots séparés par des suites de tout caractère autre que les lettres et chiffres ASCII, met en majuscule la première lettre de chaque mot et les joint. Chaque caractère du résultat est une lettre ou un chiffre.

Il existe parce que certaines cibles n’acceptent que des lettres et des chiffres dans les noms par lesquels elles adressent les ressources, alors qu’un identifiant de composant peut légitimement contenir un point, un trait d’union ou un trait de soulignement. Écrire cette conversion à la main dans chaque Recipe qui en a besoin produit plusieurs graphies d’une même idée ; un helper unique donne à chaque auteur la même réponse.

# separators become word boundaries
{{ capitalizedWords `payments-db` }} # → PaymentsDb
{{ capitalizedWords `payments_db` }} # → PaymentsDb
{{ capitalizedWords `payments.db` }} # → PaymentsDb
# a run of separators is one boundary, and leading or trailing ones add nothing
{{ capitalizedWords `-payments--db-` }} # → PaymentsDb
# characters already inside a word keep the case they were authored with
{{ capitalizedWords `MY-app` }} # → MYApp
# a word beginning with a digit is carried as authored
{{ capitalizedWords `1st-app` }} # → 1stApp
# anything outside the alphabet is a boundary, including a non-ASCII letter
{{ capitalizedWords `café-app` }} # → CafApp

🔴 Le résultat n’identifie pas le nom dont il provient. Chaque séparateur est supprimé, de sorte que deux identifiants qui ne diffèrent que par la position de leurs séparateurs aboutissent au même résultat — payments-db et payments_db donnent tous deux PaymentsDb. Le helper ne peut pas le détecter, car il voit un nom à la fois ; le repérer revient à ce qui adresse les ressources par le résultat. Une cible qui le fait refuse la collision plutôt que d’émettre un déploiement où l’un des deux manque : lors du build pour CloudFormation, deux composants dont les identifiants se réduisent à un même nom arrêtent le build, et le message nomme chaque identifiant qui y a abouti. Choisissez des identifiants qui diffèrent par plus que la ponctuation, et la question ne se pose pas.

Disponibilité par surface. capitalizedWords est enregistré partout où optional l’est : chaque surface que le moteur de rendu évalue, et la résolution d’une coordonnée source: structurée. Il n’est pas disponible dans l’interpolation des paramètres de l’Aggregate, qui n’offre que l’ensemble Sprig.

index — une clé que la map doit contenir

index <collection> <key>... lit une collection par position ou par clé, comme le fait le index propre de Go — à une différence près. Lorsque la collection est une map et que la map ne contient pas la clé, index arrête le build et nomme la clé, là où celui de Go répond par une valeur vide qui s’affiche comme le texte littéral <no value>.

# Present: returns the value
{{ index .values `replicas` }} # .values.replicas = 3 → 3
# A position in a list, or in a string, reads as Go's does
{{ index .values.zones 0 }} # .values.zones = [a, b] → a
# Absent: halts, naming the key
{{ index .values `replicas` }} # .values.replicas unset → halts: (key "replicas")

C’est la lecture à utiliser là où la clé doit être présente — un identifiant secret lu sous le nom de variable que la Recipe a calculé, une clé qu’un autre template publie — afin qu’une clé manquante arrête le build au lieu d’atteindre un artefact sous la forme <no value>. Là où la clé peut légitimement être absente, testez-la d’abord : {{ optional .values `replicas` 1 }} fournit une valeur de repli, le get de Sprig renvoie une chaîne vide, et hasKey teste sans lire. Lire via index puis appliquer default ne fournit pas de valeur de repli, parce que l’arrêt survient avant que default s’exécute. Une clé présente qui contient null n’est pas absente : index la renvoie, et elle s’affiche comme <no value>.

L’arrêt est une propriété de index seul, et il est le même sur chaque surface — les templates de valeur, l’évaluateur d’assertions, les templates de chemin, une coordonnée source: structurée, l’interpolation des paramètres de l’Aggregate, le prédicat validate: d’un paramètre et les prédicats x-aggrega-when: / x-aggrega-validate: d’un schéma. Une lecture pointée d’une clé non définie suit la politique des clés manquantes propre à sa surface et n’est pas affectée. L’arrêt est documenté dans errors/fatal-halts.md « A template indexes a map with a key the map does not hold (Un template indexe une map avec une clé que la map ne contient pas) ».

Helpers courants NON disponibles

Helm étend le text/template de Go avec des helpers de template de chart que l’on confond souvent avec des helpers Sprig généraux. Aucun d’entre eux n’est enregistré dans le moteur de rendu d’Aggrega. Les templates que le moteur de rendu d’Aggrega évalue (valuesMapping: de la Recipe, injectMapping: de la FeatureRecipe, provides, corps du Workload, l’évaluateur d’assertions) ne peuvent pas les appeler :

  • include — la forme préférée de Helm pour invoquer un fragment de template défini avec une sortie de chaîne chaînable par pipe. Le moteur de rendu d’Aggrega ne l’enregistre pas. Utilisez plutôt {{ template "name" . }} du template Go standard (la forme à effets de bord uniquement) ; pour une sortie chaînable par pipe, composez à l’aide de fragments de MappingLibrary et de directives $import:.
  • tpl — réévalue une chaîne comme template imbriqué par rapport au contexte courant. Aggrega ne l’enregistre pas ; la réévaluation imbriquée ne fait pas partie de la surface de template. Les auteurs qui ont besoin de valeurs calculées devraient les composer avec les helpers de chaîne de Sprig et émettre directement la valeur finale.
  • required — fait échouer le rendu du chart avec un message personnalisé lorsque la valeur nommée manque. Aggrega ne l’enregistre pas. L’application des champs obligatoires dans Aggrega se situe au niveau des contrats de paramètres typés (un slot parameters: d’un Aggregate avec required: true que la Release laisse non renseigné arrête le build avec E0165, en nommant le slot et l’endroit où l’Aggregate le déclare) ; les vérifications de marqueurs d’obligation par template utilisent le fail de Sprig pour lever une erreur de template fatale portant la chaîne fournie.
  • warn — émet une note non fatale dans le terminal de l’opérateur. Aggrega ne l’enregistre pas. Les templates qui doivent arrêter le rendu avec un message explicatif devraient utiliser le fail de Sprig ; les templates qui doivent se replier sur une valeur de repli sans s’arrêter devraient s’appuyer sur les branches if/else standard de Go.

Inventaire des helpers entre moteurs (essentiel pour les auteurs de MappingLibrary)

Les fragments de MappingLibrary peuvent cibler l’un de deux sites de consommation :

  • Consommation côté Aggrega (valuesMapping: de la Recipe, injectMapping: de la FeatureRecipe, etc., évalués par le moteur de rendu d’Aggrega). Les helpers disponibles sont : Sprig v3 complet (default, coalesce, quote, nindent, indent, b64enc, etc.) plus ceux propres à Aggrega (optional, capitalizedWords), et index s’arrête sur une clé que la map ne contient pas. Les helpers de template de chart (include, tpl, required, warn) sont NON disponibles.
  • Consommation interne au chart Helm (contenu values.yaml du chart ou templates/*.yaml du chart rendus en aval par le moteur de template propre de Helm). Les helpers disponibles sont : Sprig v3 complet plus les helpers de template de chart de Helm (include, tpl, required, warn). Les helpers propres à Aggrega sont NON disponibles, et index y est celui de Go, qui répond à une clé absente par une valeur vide plutôt que de s’arrêter.

Les deux ensembles de helpers partagent la surface Sprig mais divergent sur les extensions propres au moteur. Les entrées de MappingLibrary qui ciblent la consommation interne au chart Helm utilisent les conventions de Helm (racine .Values.<key> avec V majuscule, | default, composition basée sur include) ; les entrées qui ciblent la consommation côté Aggrega utilisent les conventions d’Aggrega (.values.<key> en minuscules, optional pour la valeur de repli sensible à la présence). L’entité de bibliothèque stocke les fragments tels quels ; la forme d’écriture suit l’endroit où le fragment est destiné à être rendu.

Les helpers personnalisés d’Aggrega en plus de Sprig sont optional et capitalizedWords, tous deux documentés ci-dessus, et son index remplace celui de Go, comme documenté ci-dessus. Le reste de la surface de helpers est exactement l’ensemble Sprig v3.

Références croisées