Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler o original em inglês.

Funções e helpers Sprig

O motor de templates do Aggrega liga a biblioteca de funções Sprig v3 mais os helpers próprios do Aggrega (optional e capitalizedWords) a cada template Go que o renderizador avalia, e substitui a função index do Go por uma que interrompe perante uma chave que o mapa não contém. Os autores que escrevem o valuesMapping: de uma Recipe, o injectMapping: de uma FeatureRecipe ou qualquer outra superfície de template que o renderizador avalia têm à disposição o conjunto completo de helpers do Sprig, a par das funções nativas de text/template do Go e dos campos do contexto de execução documentados em template-context-contract.md.

🔴 A expressão «que o renderizador avalia» deve ler-se como o âmbito que é, porque uma superfície de autoria fica fora dele. Uma coordenada source: estruturada é resolvida para que o artefacto que nomeia possa ser fixado, e essa resolução não é uma passagem de renderização: regista os helpers próprios do Aggrega e nada mais, pelo que uma chamada Sprig num campo source:, ou numa entrada locals: que ele lê, interrompe o pull. Uma entrada que nenhum campo source: lê é avaliada apenas pela renderização, com o conjunto completo. Resolver uma coordenada determina o que é fixado em vez de produzir um artefacto, e é por isso que o seu conjunto de funções é deliberadamente mais restrito — consulte errors/fatal-halts.md «Resolving a source: coordinate registers a narrower function set (A resolução de uma coordenada source regista um conjunto de funções mais restrito)» para a interrupção e a forma portável a usar em alternativa.

O conjunto do Sprig é registado isoladamente para a interpolação de parâmetros, e juntamente com os helpers próprios do Aggrega nas superfícies de template de valor do renderizador.

O que está ligado

O Sprig v3 expõe toda a sua superfície de helpers — cerca de 200 funções nas categorias abaixo. Esta página esboça as categorias com os helpers comuns de cada uma; a referência canónica por função é a documentação upstream do Sprig.

  • Strings — upper, lower, title, trim, trimAll, trimPrefix, trimSuffix, replace, contains, hasPrefix, hasSuffix, substr, quote, squote, cat, indent, nindent, repeat, helpers de estilo de nome (snakecase, camelcase, kebabcase), helpers de abreviatura (abbrev, abbrevboth, trunc), helpers de checksum (sha1sum, sha256sum, sha512sum, adler32sum), toString.
  • Listas — list, tuple, first, last, rest, initial, append/push, prepend, concat, reverse, uniq, without, has, slice, chunk, join, splitList, split, splitn, sortAlpha, compact.
  • Dicionários — dict, get, set, unset, hasKey, keys, values, pick, omit, pluck, merge, mergeOverwrite, dig, deepCopy.
  • Matemática — add, sub, mul, div, mod, add1, min, max, ceil, floor, round, mais as variantes decimais com o sufixo f (addf, subf, mulf, divf, minf, maxf).
  • Conversão — int, int64, float64, atoi, toString, toDecimal, seq, until, untilStep.
  • Codificação — b64enc, b64dec, b32enc, b32dec, toJson, toPrettyJson, toRawJson, fromJson, mais as variantes JSON com o prefixo must que expõem erros de descodificação em vez de pôr silenciosamente a zero.
  • Verificações de tipo — typeOf, typeIs, typeIsLike, kindOf, kindIs, deepEqual, empty.
  • Valores predefinidos e fluxo — default, coalesce, all, any, ternary, fail (gera um erro de template com uma mensagem personalizada — a forma canónica de abortar uma renderização com uma mensagem de guarda).
  • Regex — regexMatch, regexFind, regexFindAll, regexReplaceAll, regexReplaceAllLiteral, regexSplit, regexQuoteMeta, mais as variantes estritas com o prefixo must.
  • Caminhos — base, dir, clean, ext, isAbs (estilo Unix); osBase, osClean, osDir, osExt, osIsAbs (conforme o sistema operativo).
  • SemVer — semver, semverCompare.
  • URL — urlParse, urlJoin.
  • Datas — ago, date, dateInZone, dateModify, duration, durationRound, htmlDate, htmlDateInZone, now, toDate, unixEpoch.

Ressalva sobre o determinismo

O Aggrega garante uma saída idêntica byte a byte para uma entrada idêntica byte a byte. Um subconjunto dos helpers do Sprig lê o estado do ambiente e quebra essa garantia quando invocado a partir de um template. Os autores devem evitar os seguintes helpers nas superfícies de template que contribuem para artefactos renderizados:

  • Leitores do relógio do sistema — now, date, dateInZone, dateModify, htmlDate, htmlDateInZone, ago quando chamado sem uma hora de referência fixa.
  • Geradores aleatórios — randAlpha, randAlphaNum, randAscii, randNumeric, randBytes, randInt, uuidv4.
  • Leitores do ambiente — env, expandenv (leem variáveis de ambiente do processo, que diferem entre os postos de trabalho dos operadores e os runners de CI).
  • Resolvedores de rede — getHostByName.

Estes helpers não são bloqueados pelo motor; fazem parte do conjunto do Sprig v3. A disciplina de os evitar em templates do caminho de renderização é mantida pelos revisores e pela garantia de saída determinística da qual dependem os autores e o catálogo da biblioteca padrão.

Números num template de valor

Um número que um autor escreve chega a um template de valor como número. Um número sem parte decimal é um inteiro e é impresso inteiro: 1000000 imprime 1000000. Qualquer outro número é impresso na sua forma decimal exata mais curta, nunca em notação exponencial: um 0.0000001 escrito pelo autor imprime 0.0000001 e um 1e21 escrito pelo autor imprime 1000000000000000000000, quer o template escreva o valor diretamente, quer o converta em texto com toString, quote, printf "%v" ou toJson. Um número que uma função matemática devolve — mulf, float64, round e afins — é o valor próprio dessa função e é impresso na forma própria dessa função, que é a notação exponencial para um valor muito pequeno ou muito grande: {{ mulf .values.ratio 1 }} imprime 1e-07 para um 0.0000001 escrito pelo autor.

As comparações — eq, ne, lt, le, gt e ge — leem dois números pelo valor, seja qual for o tipo que transporta cada um, pelo que um inteiro escrito pelo autor se compara com um decimal escrito no template, e 3 é igual a 3.0:

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

Um número nunca é comparado com um texto: qualquer uma das seis, ao receber um número e um texto entre aspas, interrompe a compilação, nomeando os dois tipos. Deve comparar o número com um número escrito sem aspas ou convertê-lo primeiro em texto:

{{ 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

A interrupção é A value template failed while it ran (Um template de valores falhou durante a execução). Uma asserção lê um número escrito pelo autor da mesma forma; consulte Números nesta superfície.

Presença e vazio — duas perguntas diferentes

Um template faz uma de duas perguntas sobre um valor, e cada pergunta tem os seus próprios helpers.

  • Foi o autor que o escreveu? hasKey e optional respondem pela presença. Uma chave que o autor escreveu está presente seja qual for o seu conteúdo — 0, "" e false incluídos — e apenas uma chave que o autor omitiu está ausente.
  • Está vazio? default, with, if e empty respondem pelo vazio. 0, "", false, uma lista vazia, um mapa vazio e um valor ausente contam todos como vazios aí, tal como no Helm.
.values.replicashasKey .values "replicas"optional .values "replicas" 1.values.replicas | default 1if .values.replicas
ausentefalse11false
0true01false
3true33true

Um valor que pode legitimamente ser 0, "" ou false — um número de réplicas igual a zero, um timeout igual a zero, uma flag desligada — é testado com hasKey ou optional, para que o 0 do autor chegue à saída como 0. default, with e if servem para um valor cuja forma vazia não tem significado próprio, em que «vazio» e «não escrito» podem ser tratados da mesma forma. Cada chave deve ser lida de uma única maneira por template: uma chave que o template também lê como caminho com pontos conta como presente, como descreve o limite de optional.

Helpers específicos do Aggrega

optional — valor alternativo sensível à presença

optional <map> <key> <fallback> devolve o valor em <key> dentro de <map> se a chave estiver presente; caso contrário, devolve <fallback>. Ao contrário do default do Sprig, optional distingue «chave ausente» de «chave presente com um valor zero, vazio ou falso».

A assinatura recebe o mapa e a chave como argumentos separados porque um valor passado pelo operador | do template Go perdeu o acesso ao seu mapa pai. Sem o mapa pai no âmbito, não é possível verificar a presença.

Um limite à verificação de presença, e vem do template e não do helper: um template de valor lê uma chave ausente como nada, o que faz fornecendo um valor vazio em cada chave ausente que o template nomeia como caminho com pontos e lê como valor. Assim, um template que lê uma chave tanto através de optional como através desse caminho encontra essa chave presente e vazia, e obtém o valor vazio em vez do valor alternativo. Lendo cada chave de uma única maneira por template, as duas respostas coincidem.

# 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

O último caso é a distinção que o default do Sprig não consegue fazer. {{ .infra.replicas | default 1 }} devolve 1 quer replicas tenha sido escrito como 0, quer tenha sido omitido — a confusão que impede os padrões legítimos de scale-to-zero, sem novas tentativas, sem timeout e de flag a falso.

Convenção para as aspas das chaves: preferir acentos graves. Os templates Go aceitam para o argumento de chave tanto literais de string entre aspas duplas ("replicas") como entre acentos graves (`replicas`); ambos produzem a mesma string no momento da avaliação do template. Os exemplos do catálogo e da documentação usam uniformemente a forma com acentos graves porque é segura para YAML em qualquer contexto de aspas. Uma chave entre aspas duplas dentro de um escalar YAML entre aspas duplas termina a string YAML a meio do 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 }}"

Quando o template está dentro de um escalar de bloco YAML (forma |) ou como escalar de valor simples, ambas as formas são renderizadas corretamente. Quando o template está incorporado num escalar YAML entre aspas duplas (o padrão field: "{{ ... }}" de valor de campo como template), os acentos graves são obrigatórios. A convenção única (sempre acentos graves) evita por completo a armadilha das aspas do YAML.

Quando preferir optional a default. Deve usar-se optional quando o campo pode legitimamente ser zero, vazio ou falso e o autor do catálogo precisa de distinguir «o autor não definiu isto» de «o autor definiu isto com um valor falsy». Deve usar-se default quando a confusão é aceitável (p. ex., campos de string em que vazio é inválido; campos numéricos em que zero é inválido).

Disponibilidade por superfície. optional está registado em todas as superfícies que o renderizador avalia: as superfícies de template de valor (valuesMapping da Recipe, injectMapping da FeatureRecipe, provides, pipeline.with, o corpo do Workload), o avaliador de asserções e os templates de caminho (directory: / subDirectory: nas fronteiras da Release). O que difere na superfície de templates de caminho não é o conjunto de helpers, mas a política de chave em falta: um template de caminho trata uma chave ausente como erro e não como vazia, porque um segmento de caminho silenciosamente vazio produz uma estrutura de sistema de ficheiros danificada que só é descoberta depois da compilação. optional lê uma chave sem que essa política estrita seja acionada primeiro, e é isso que o torna utilizável aí.

capitalizedWords — reduzir um nome a letras e dígitos

capitalizedWords <string> lê o seu argumento como palavras separadas por sequências de qualquer carácter fora das letras e dígitos ASCII, coloca em maiúscula a primeira letra de cada palavra e junta-as. Cada carácter do resultado é uma letra ou um dígito.

Existe porque alguns destinos aceitam apenas letras e dígitos nos nomes pelos quais endereçam recursos, enquanto um id de componente pode legitimamente conter um ponto, um hífen ou um sublinhado. Escrever essa conversão à mão em cada Recipe que dela precisa produz várias grafias de uma mesma ideia; um único helper dá a todos os autores a mesma resposta.

# 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

🔴 O resultado não identifica o nome de onde provém. Cada separador é descartado, pelo que dois ids que diferem apenas na posição dos seus separadores chegam ao mesmo resultado — payments-db e payments_db dão ambos PaymentsDb. O helper não o consegue detetar, porque vê um nome de cada vez; apanhá-lo cabe ao que endereça recursos pelo resultado. Um destino que o faz rejeita a colisão em vez de emitir uma implementação em que falta um dos dois: na compilação para CloudFormation, dois componentes cujos ids se reduzem a um mesmo nome interrompem a compilação, e a mensagem nomeia cada id que lá chegou. Escolhendo ids que difiram em mais do que a pontuação, a questão não se coloca.

Disponibilidade por superfície. capitalizedWords está registado onde quer que optional esteja: em todas as superfícies que o renderizador avalia e na resolução de uma coordenada source: estruturada. Não está disponível na interpolação de parâmetros do Aggregate, que oferece apenas o conjunto do Sprig.

index — uma chave que o mapa tem de conter

index <collection> <key>... lê uma coleção por posição ou por chave, tal como o próprio index do Go — com uma diferença. Quando a coleção é um mapa e o mapa não contém a chave, index interrompe a compilação e nomeia a chave, enquanto o do Go responde com um valor vazio que é impresso como o texto literal <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")

É a leitura a usar onde a chave tem de estar presente — uma credencial lida sob o nome de variável que a Recipe calculou, uma chave que outro template publica — para que uma chave em falta pare a compilação em vez de chegar a um artefacto como <no value>. Onde a chave pode legitimamente estar ausente, deve testá-la primeiro: {{ optional .values `replicas` 1 }} fornece um valor alternativo, o get do Sprig devolve uma string vazia e hasKey testa sem ler. Ler através de index e depois aplicar default não fornece um valor alternativo, porque a interrupção ocorre antes de default ser executado. Uma chave que está presente e contém null não está ausente: index devolve-a, e é impressa como <no value>.

A interrupção é uma propriedade apenas de index, e é a mesma em todas as superfícies — os templates de valor, o avaliador de asserções, os templates de caminho, uma coordenada source: estruturada, a interpolação de parâmetros do Aggregate, o predicado validate: de um parâmetro e os predicados x-aggrega-when: / x-aggrega-validate: de um esquema. Uma leitura com ponto de uma chave não definida segue a política de chave em falta da sua própria superfície e não é afetada. A interrupção está documentada em errors/fatal-halts.md «A template indexes a map with a key the map does not hold (Um template indexa um mapa com uma chave que o mapa não contém)».

Helpers comuns NÃO disponíveis

O Helm estende o text/template do Go com helpers de template de chart que são frequentemente confundidos com helpers gerais do Sprig. Nenhum deles está registado no renderizador do Aggrega. Os templates que o renderizador do Aggrega avalia (valuesMapping: da Recipe, injectMapping: da FeatureRecipe, provides, o corpo do Workload, o avaliador de asserções) não os podem chamar:

  • include — a forma preferida do Helm para invocar um fragmento de template definido com uma saída de string encadeável por pipe. O renderizador do Aggrega não o regista. Deve usar-se em alternativa {{ template "name" . }} do template Go padrão (a forma apenas com efeitos secundários); para uma saída encadeável por pipe, deve compor-se com fragmentos de MappingLibrary e diretivas $import:.
  • tpl — reavalia uma string como template aninhado em relação ao contexto atual. O Aggrega não o regista; a reavaliação aninhada não faz parte da superfície de templates. Os autores que precisam de valores calculados devem compô-los com os helpers de string do Sprig e emitir diretamente o valor final.
  • required — faz falhar a renderização do chart com uma mensagem personalizada quando o valor nomeado está em falta. O Aggrega não o regista. A aplicação dos campos obrigatórios no Aggrega situa-se na camada dos contratos de parâmetros tipados (um slot parameters: de um Aggregate com required: true que a Release deixa por preencher interrompe a compilação com E0165, nomeando o slot e o local onde o Aggregate o declara); as verificações de marcadores de obrigatoriedade por template usam o fail do Sprig para gerar um erro de template fatal que transporta a string fornecida.
  • warn — emite uma nota não fatal no terminal do operador. O Aggrega não o regista. Os templates que precisam de interromper a renderização com uma mensagem explicativa devem usar o fail do Sprig; os templates que precisam de recorrer a um valor alternativo sem interromper devem apoiar-se nas ramificações if/else padrão do Go.

Inventário de helpers entre motores (fundamental para os autores de MappingLibrary)

Os fragmentos de MappingLibrary podem ter como destino um de dois locais de consumo:

  • Consumo do lado do Aggrega (valuesMapping: da Recipe, injectMapping: da FeatureRecipe, etc., avaliados pelo renderizador do Aggrega). Os helpers disponíveis são: o Sprig v3 completo (default, coalesce, quote, nindent, indent, b64enc, etc.) mais os próprios do Aggrega (optional, capitalizedWords), e index interrompe perante uma chave que o mapa não contém. Os helpers de template de chart (include, tpl, required, warn) NÃO estão disponíveis.
  • Consumo interno ao chart do Helm (conteúdo de values.yaml do chart ou templates/*.yaml do chart renderizados a jusante pelo próprio motor de templates do Helm). Os helpers disponíveis são: o Sprig v3 completo mais os helpers de template de chart do Helm (include, tpl, required, warn). Os helpers próprios do Aggrega NÃO estão disponíveis, e index aí é o próprio do Go, que responde a uma chave ausente com um valor vazio em vez de interromper.

Os dois conjuntos de helpers partilham a superfície do Sprig, mas divergem nas extensões específicas do motor. As entradas de MappingLibrary destinadas ao consumo interno ao chart do Helm usam as convenções do Helm (raiz .Values.<key> com V maiúsculo, | default, composição baseada em include); as entradas destinadas ao consumo do lado do Aggrega usam as convenções do Aggrega (.values.<key> em minúsculas, optional para o valor alternativo sensível à presença). A entidade de biblioteca guarda os fragmentos literalmente; a forma de criação segue o local onde o fragmento se destina a ser renderizado.

Os helpers personalizados do Aggrega para além do Sprig são optional e capitalizedWords, ambos documentados acima, e o seu index substitui o do Go, como documentado acima. O resto da superfície de helpers é exatamente o conjunto do Sprig v3.

Referências cruzadas