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

Superfície de validação

O Aggrega valida o conteúdo escrito em quatro camadas de schema distintas. Cada camada cobre um escopo diferente, é executada em um ponto diferente do pipeline de compilação e produz erros com uma forma diferente. Os autores que encontram um erro de validação se beneficiam de saber qual camada rejeitou a entrada — o mesmo campo pode ser regido por mais de uma camada, e a camada que disparou determina o que corrigir e onde.

Esta página documenta as quatro camadas, seu posicionamento no pipeline, a convenção de forma de erro que cada camada segue e como as camadas interagem quando mais de uma se aplica ao mesmo campo.

As quatro camadas

Camada 1 — Envelope JSON Schema

Escopo. A forma estrutural de todo YAML do catálogo: apiVersion, kind, metadata.{name, version, description, maintainers, license, ...}, o bloco spec: de nível superior e os campos obrigatórios por entidade que o schema declara. Cada tipo de entidade (Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest, Plugin, Release, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary) tem seu próprio JSON Schema, documentado na Referência de esquemas. O Workload também tem um lá, e é o único tipo desse conjunto que um autor escreve dentro de outra entidade — o bloco workload: de uma Recipe ou de uma FeatureRecipe, ou uma entrada de uma WorkloadLibrary — em vez de como um arquivo de catálogo próprio; a mesma verificação do envelope o rege onde quer que seja escrito, e o aggrega validate aceita diretamente um arquivo Workload como alvo de entidade única.

Execução da validação. Na resolução (resolver / carregamento), por arquivo. Cada documento é verificado contra o JSON Schema do seu tipo quando é carregado; uma chave fora dos campos que o schema declara é recusada ali, antes que qualquer outra validação seja executada.

Formato do erro. Uma incompatibilidade com o schema é relatada como uma falha do envelope do documento. Seu cabeçalho traz a categoria do documento com falha — [CATALOG_ERROR E0215] para uma entidade do catálogo, [DEVELOPER_ERROR E0215] para um Aggregate, [OPS_ERROR E0215] para uma Release — e a mensagem nomeia o tipo, o arquivo, a linha e a coluna, o caminho do campo e a restrição violada:

[CATALOG_ERROR E0215] <path>
document envelope validation failed (Recipe, at <path>); 11:3: spec.foo: unexpected property: "foo". correct the document to match its kind's schema

Omissões de campos obrigatórios e incompatibilidades de tipo aparecem no mesmo formato — spec.capability: missing required property: capability, metadata.version: type: 1 has type "integer", want "string".

Camada 2 — Schemas dos pilares (schema: / featuresSchema / usesSchema)

Escopo. Os pilares de dados que uma entidade carrega — values, infra, parameters, além do bloco de anexos features: cujos slots o featuresSchema declara e do bloco uses: regido pelo usesSchema. As entidades do Domínio 2 (Component, Feature) incorporam declarações JSON Schema 2020-12 em seu envelope YAML (spec.schema inline — na forma compacta ou completa — ou um $ref: para uma entrada compartilhada de uma SchemaLibrary); as entidades do Domínio 3 (Recipe, FeatureRecipe) consomem os schemas resolvidos durante sua própria passagem de validação.

Execução da validação. Na resolução, depois que o envelope JSON Schema é aprovado. O compilador compõe o schema: escrito da entidade com bases geradas automaticamente, derivadas das declarações usesSchema e featuresSchema; o schema composto valida os blocos values: / infra: / features: / uses: fornecidos pelo desenvolvedor em cada instância de componente no Aggregate.

Formato do erro. Violações de restrições aparecem como mensagens que nomeiam a entidade, o caminho dentro do pilar e a regra que rejeitou o valor — por exemplo, um desenvolvedor definindo uma porta como 80 diante de uma regra do schema que exige >=1024.

Uma entrada usesSchema ou featuresSchema redeclarada não produz nenhuma falha de composição. Essas duas superfícies se sobrepõem por nome: a entrada de um filho substitui integralmente a da base, schema e seletor juntos, de modo que não há conflito a relatar entre uma entrada da base e uma do filho.

Camada 3 — Capacidade do Provider para o modo sintetizado

Escopo. Regido pela verificação de capacidade do modo sintetizado do provedor vinculado:

  • O suporte ao modo sintetizado (workload:) depende da capacidade do provedor vinculado, não da presença de workloadSchema: uma Recipe workload: vinculada a um provedor que não consegue sintetizar é rejeitada aqui. O catálogo da biblioteca padrão declara workloadSchema nos provedores capazes de síntese por convenção — no spec.provider.workloadSchema do Plugin de renderização de provedores — como o contrato de tradução documentado. Esse corpo de workloadSchema é, por sua vez, compilado para JSON Schema 2020-12 quando o Plugin é carregado, uma verificação estrutural de aceitação que rejeita um schema malformado no carregamento, e não na renderização.

Execução da validação. Na renderização base, depois que o valuesMapping da própria Recipe foi resolvido. A camada 3 condiciona o despacho no modo sintetizado à capacidade do provedor.

Formato do erro. Uma recusa por capacidade é atribuída ao domínio de autoria do catálogo, por isso seu relatório começa com um cabeçalho entre colchetes que traz essa categoria e a instância responsável pela falha. A mensagem começa com a frase fixa que enuncia a condição e depois nomeia o nó, o provedor e os tipos que esse provedor suporta:

[CATALOG_ERROR] instance <node-id>: provider does not support the node's input kind (node "<node-id>"). provider "<provider-name>" does not support synthesized recipes (this provider supports: <kinds>); declare one of the supported input kinds, or target a provider that supports synthesized

O cabeçalho [CATALOG_ERROR] sinaliza que a entidade do catálogo está com falha, e não o Aggregate do desenvolvedor. Em um terminal, o cabeçalho também traz o código curto da condição — E0265 para esta, que a tabela de todas as condições resolve — e a mensagem passa para sua própria linha recuada; a forma de uma linha acima é a que chega a um log. A frase inicial é fixa por condição, então é a parte a usar na correspondência quando você trabalha a partir do texto; tudo o que vem depois varia com o nó com falha.

Uma salvaguarda relacionada protege o próprio despacho para provedores: quando mais de um Plugin de renderização de provedores atende ao mesmo alvo, o espaço de trabalho resolve a ambiguidade por meio de uma vinculação de provedor em .aggrega-config.yaml, escolhida no aggrega pull e registrada no lockfile. Sem vinculação e com exatamente um Plugin candidato, esse candidato é usado; sem vinculação e com mais de um candidato, o build é interrompido de forma explícita, nomeando os plugins candidatos. A ambiguidade é resolvida por espaço de trabalho no ponto de uso, não por uma regra de unicidade válida para todo o catálogo.

Validação do conteúdo de Workload por provedor. O spec.provider.workloadSchema de um Plugin de renderização de provedores documenta como o provedor traduz um Workload e marca o provedor como capaz de sintetizar um; ele não valida nada. Todo corpo de Workload é validado contra o schema Workload da plataforma, qualquer que seja o provedor.

Camada 4 — Validação de valores das vinculações de anotações

Escopo. Valores de anotação escritos em fronteiras da Release / componentes de fronteira ou em subsistemas / instâncias de componente do Aggregate, quando uma vinculação do Manifest em mappings.features.annotations.<key> declara roteamento por meio de listas de caminhos pontuados maps.infra e/ou maps.values. Cada caminho declarado navega pelo spec.schema.<pillar> da Feature de destino até uma propriedade folha; a contribuição do valor da anotação nessa folha é validada contra o tipo declarado pelo schema da Feature. A validação passa pela própria declaração JSON Schema 2020-12 da Feature — as vinculações declaram apenas o roteamento, não fragmentos de validação.

Execução da validação. A subfase de expansão de anotações da resolução, depois da validação dos alvos de vinculação do Manifest (a verificação no carregamento do catálogo que confirma que cada caminho declarado existe no schema da Feature referenciada) e junto à validação de schemas da camada 2 sobre anexos explícitos. Para cada anotação efetiva por componente: analisar o valor como um escalar, um mapa estruturado ou um null explícito; rotear por subchave por meio da declaração maps da vinculação, agrupada por pilar, com a imposição lado-versus-pilar (o lado do Aggregate aciona maps.values; o lado da Release aciona maps.infra); validar o valor de runtime por folha contra o tipo declarado pelo schema da Feature no pilar roteado. Vários erros de subchave são coletados e todos emitidos antes da interrupção.

Formato do erro. Os erros de validação de schema nesta camada seguem o formato da camada 2 — entidade, caminho (chave da anotação mais roteamento da subchave), detalhe da restrição. As violações da partição lado-versus-pilar e as falhas de roteamento ambíguo são atribuídas ao documento em que o valor da anotação foi escrito, de modo que uma falha carregada por um Aggregate abre um cabeçalho [DEVELOPER_ERROR] e uma carregada por uma Release abre um cabeçalho [OPS_ERROR], e ambas nomeiam a chave da anotação, o pilar roteado, o lado de autoria e a localização na fonte.

Uma única convenção de formatação de erros em todas as camadas

As quatro camadas compartilham uma convenção observável: toda falha de validação atribuível ao Aggrega traz um formato de caminho mais justificativa que nomeia o campo infrator e a restrição que o rejeitou.

  • Os erros da camada 1 (envelope) e da camada 2 (schemas dos pilares) começam com o mesmo cabeçalho entre colchetes — a categoria do documento com falha e o código curto da condição, como [CATALOG_ERROR E0215] para uma incompatibilidade do envelope em uma entidade do catálogo e [DEVELOPER_ERROR E0168] para um valor de um Aggregate que um schema de pilar recusa — seguido do caminho do campo e da regra do schema violada.
  • Os erros da camada 3 (fonte do Provider / Workload) são, por definição, atribuíveis a entidades do catálogo — o par Recipe + Provider escreveu o schema que rejeitou a entrada do desenvolvedor. Eles são atribuídos ao domínio de autoria do catálogo, e a atribuição chega até você no cabeçalho entre colchetes do diagnóstico, e não como uma palavra digitada na mensagem: um relatório que interrompe a execução começa com [CATALOG_ERROR E0nnn], em que a categoria nomeia o domínio e o código curto nomeia a condição. Faça a correspondência pelo código curto, que é fixo depois de emitido.
  • Os erros da camada 4 (validação de valores das vinculações de anotações) seguem o formato da camada 2 — o schema da Feature que valida reside no spec.schema da Feature referenciada, e os valores de runtime fluem pelo roteamento maps da vinculação do Manifest para esse schema para a verificação de tipos por folha.

Para o inventário completo das sentinelas com prefixo Aggrega e das superfícies que as produzem, consulte errors/error-translation.md. Para o catálogo por erro (as regras de formato da Recipe [CATALOG_ERROR], condição por condição), consulte errors/fatal-halts.md.

Interação entre camadas quando os campos se sobrepõem

O mesmo campo escrito pode ser regido por mais de uma camada. O containers.<name>.ports.<port> de um Workload é verificado pela camada 1 como parte da forma estrutural do schema Workload; a camada 2 não o alcança, já que o conteúdo de um Workload é uma estrutura interna da Recipe, e não um pilar de Component; e o workloadSchema de um provedor não verifica nada — por isso uma restrição como recusar uma porta abaixo de 1024 pertence ao schema do Component ou a uma asserção, onde a camada que dispara a nomeia.

Resumo do posicionamento no pipeline

CamadaEscopoExecuta emPrefixo do erro
1 — Envelope de JSON SchemaForma estrutural (apiVersion, kind, metadata, spec de nível superior)Resolução (carregamento)a categoria do documento com E0215 — [CATALOG_ERROR E0215] para uma entidade do catálogo
2 — Schemas dos pilares (schema: / featuresSchema / usesSchema)Validação de dados por pilar (values, infra, secrets, uses)Resolução (depois do envelope)a categoria do documento de autoria com o código curto da condição — [DEVELOPER_ERROR E0168] para um valor de um Aggregate
3 — Verificação de capacidade do ProviderSuporte ao modo sintetizado (capacidade do provedor)Renderização base[CATALOG_ERROR]
4 — Validação de valores das vinculações de anotaçõesContribuições de valores de anotação roteadas para o spec.schema da Feature de destino por meio dos caminhos maps da vinculação do ManifestA subfase de expansão de anotações da resolução, junto à camada 2erro de validação de schema; as superfícies lado-versus-pilar / de roteamento ambíguo abrem o domínio próprio do documento de autoria — [DEVELOPER_ERROR] a partir de um Aggregate, [OPS_ERROR] a partir de uma Release

Referências cruzadas

  • errors/error-translation.md — inventário das sentinelas com prefixo Aggrega e das superfícies que as produzem.
  • errors/fatal-halts.md — catálogo por erro de cada interrupção fatal que o compilador emite.
  • vocabulary/data-pillars.md — os pilares de dados (values, infra, parameters, locals, features:, uses: e provides) que a camada 2 valida.
  • entities/component.md — superfície de autoria do Component para schema: / featuresSchema / usesSchema.
  • entities/plugin.md — superfície de autoria do Plugin de renderização de provedores para spec.provider.workloadSchema.
  • entities/manifest.md — superfície de vinculação features.annotations do Manifest (camada 4).
  • providers/well-known-annotations.md — análise dos valores de anotação, roteamento por subchave de valores estruturados, exclusão com null por subchave e composição entre lados que a camada 4 valida.