extends e implements
Herança através de extends
As entidades do catálogo (Component, Feature) suportam herança simples através da palavra-chave extends, que permite aos arquitetos de plataforma construir entidades especializadas sobre uma base partilhada. A fusão profunda do envelope YAML é comum aos dois tipos: os metadados, as etiquetas e as tabelas estruturais declarativas da entidade que estende sobrepõem-se às chaves correspondentes da base, e os mapas aninhados são fundidos recursivamente. Os dois tipos separam-se nos pilares de dados.
Esta página trata dos tipos do catálogo, e estes não são os únicos tipos que declaram extends. Uma Release e um Manifest também o declaram, e ambos são documentos do lado da implementação escritos lado a lado, em vez de entidades indexadas no catálogo — por isso as suas referências nomeiam ficheiros, não entidades do catálogo, e o que é fundido é uma superfície de criação e não um esquema. Para esses, ver entities/release.md e entities/manifest.md.
O extends de um Component compõe a estrutura e herda os pilares por inteiro
Para um Component, extends compõe metadata.labels, metadata.annotations, spec.featuresSchema (slots de anexo), spec.usesSchema (sockets de topologia) e spec.inject (a lista de permissões do self-inject, cujas entradas são concatenadas começando pela base e sem duplicados). Os três pilares de dados — values, infra, provides — não são compostos. Um Component que estende não escreve conteúdo de pilar: escreve o marcador literal schema: inherited e recebe o bloco schema: da base exatamente como a base o escreveu, em qualquer profundidade de uma cadeia.
O esquema Component publicado torna esse marcador simultaneamente obrigatório e exclusivo, e rejeita cada desvio em relação a ele quando o documento é carregado, com um diagnóstico próprio para cada um: conteúdo de pilar escrito sob schema: num Component que declara extends:; schema: totalmente omitido nesse caso; e schema: inherited num Component que não declara nenhum extends:.
Daí decorrem duas consequências, que puxam em direções opostas:
- O conjunto de chaves é fixado pela base. Um Component que estende não declara chaves de pilar, pelo que não pode ocultar, remover nem mudar o tipo de uma que a base declara, e não acrescenta nenhuma própria. Uma instância da base e uma instância de qualquer coisa que a estenda são validadas face ao mesmo contrato de pilar.
- O reforço passa para
assertions:. Uma especialização que tem de admitir menos do que os pilares herdados admitem exprime-o como um predicado sobre si própria, não como uma folha de esquema restringida. Se uma basecore/base-serverdeclarartls_enabled: { type: boolean, default: true }, uma especialização que exige TLS incondicionalmente escreve:
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/tls-only-server version: 1.0.0 labels: component.aggrega.ai/type: "server"spec: extends: core/base-server schema: inherited # values, infra and provides are the base's, verbatim assertions: tls-is-mandatory: | {{- if not .values.tls_enabled -}} {{- fail "this component requires tls_enabled: true" -}} {{- end -}}A regra rejeita um valor que o bloco de pilar herdado aceita, que é exatamente o que reforçar significa aqui. A direção inversa não tem qualquer expressão: uma especialização não pode relaxar uma restrição herdada, porque não pode reformular a folha que a contém. Ver entities/component.md «Catalog Authoring: Extending Base Components (Criação no catálogo: estender Components base)» para a tabela de composição completa e o par completo de base e extensão.
O extends de uma Feature compõe os seus pilares
Para uma Feature, o schema: da filha compõe-se com o da base segundo a semântica de composição do JSON Schema 2020-12, produzindo um único esquema fundido face ao qual uma instância escrita é validada. As Features de credenciais — as que têm a etiqueta feature.aggrega.ai/kind: secret — usam isto para construir sobre uma base partilhada: uma Feature de credenciais filha estende um pai para herdar o seu esquema de consulta ao vault, estreitando ao mesmo tempo as restrições.
O compilador não toma posição sobre a direção dessa alteração. A composição é estrutural, pelo que uma restrição da filha que alarga a da base é composta sem interromper a compilação e surge como um aviso. Nada a rejeita: a restrição de uma base de Feature é uma expectativa partilhada que os autores do catálogo mantêm através de revisão, não um contrato que a plataforma faz cumprir.
Associação de interface através de implements
As Recipes e as FeatureRecipes associam-se a uma interface de Component ou de Feature através da palavra-chave implements: no topo do seu spec. A associação declara de que interface do catálogo esta Recipe / FeatureRecipe é a implementação concreta, e suporta três formas de correspondência de versões:
- Exata —
implements: core/api-server:1.0.0— corresponde a uma versão específica do tipo de Component. - Intervalo compatível com a versão principal —
implements: core/api-server:^1.0.0— corresponde a qualquer versão que satisfaça>=1.0.0, <2.0.0(compatível com a versão principal segundo o SemVer). Usa-se quando uma Recipe suporta um intervalo compatível em vez de uma única versão fixada. - Sem versão —
implements: core/api-server— corresponde a qualquer versão do tipo de Component. Usa-se quando uma Recipe serve todas as versões do tipo.
implements: nunca seleciona uma Recipe: quem o faz é o mapeamento do Manifest. O que a declaração determina é a verificação de consistência em cada entrada de mapeamento — a versão do tipo mapeado tem de satisfazer o implements: da Recipe mapeada numa das três formas, ou a Recipe tem de implementar uma base que esse tipo estende — e a lista de candidatos que o diagnóstico de mapeamento em falta e a conclusão automática do editor oferecem. Uma entrada de mapeamento cuja Recipe tem um implements: que não corresponde nem ao tipo mapeado nem a nenhuma das suas bases interrompe a compilação, indicando o mapeamento, a Recipe e o seu valor implements:. Quando uma chave components.type alcança uma instância de componente numa versão que a chave não indica — todas as instâncias, no caso de uma chave escrita sem versão —, a verificação é feita de novo com o tipo próprio dessa instância, na versão com que a compilação a processa, e uma Recipe que não a satisfaça interrompe a compilação da mesma forma, indicando a instância.
A associação implements: é o mecanismo que faz funcionar «o mesmo tipo de Component, Recipes diferentes para fornecedores diferentes»: um Component core/postgres pode ter uma Recipe que o implementa para o fornecedor helm e outra Recipe que o implementa para o fornecedor compose. Cada Recipe declara o mesmo valor implements:, e o Manifest com que uma Release é compilada mapeia o tipo para aquela que ela pretende.
Uma Recipe escrita para uma base serve tudo o que a estende
implements: indica uma base, e uma Recipe que indica uma é a implementação concreta para cada Component que estende essa base, em qualquer profundidade da cadeia. Assim, uma especialização construída com extends não precisa de uma Recipe própria — e é isso que torna barato consumir um wrapper publicado: a equipa que o publica escreve um Component, e as equipas que o implementam reutilizam as Recipes da base em todos os destinos.
Aqui valem dois factos ao mesmo tempo, e são distintos. Um leitor que os reduza a «a especialização não precisa de nada» escreve um Manifest que falha, por um motivo que irá procurar no ficheiro errado:
- A Recipe corresponde. A verificação de consistência entre a chave de tipo de um mapeamento do Manifest e o
implements:da Recipe mapeada aceita o mapeamento quando a Recipe implementa o próprio tipo mapeado ou qualquer base que esse tipo estende. As três formas de versão acima aplicam-se a uma base exatamente como ao próprio tipo: uma Recipe que declaraimplements: core/base-server:^1.0.0satisfaz uma especialização cuja base está na versão1.4.0, e não satisfaz uma cuja base está em2.0.0. - O Manifest continua a mapear o tipo próprio da especialização. A seleção da Recipe faz-se pela chave de mapeamento exata. Uma instância de
enterprise/labelled-serverprecisa da sua própria entradamappings.components.type; não herda a entrada escrita paracore/base-server. Uma especialização sem entrada própria é interrompida com o diagnóstico de instância não mapeada mesmo quando a sua base está mapeada.
O custo de criação de uma especialização é, portanto, uma linha de Manifest e nenhuma Recipe nova:
# The wrapper extends core/base-server and authors no pillars.# core/helm/base-server declares: implements: core/base-serverspec: mappings: components: type: enterprise/labelled-server:1.0.0: core/helm/base-server:1.0.0Quando a cadeia extends do tipo mapeado não pode ser percorrida — forma um ciclo, ou uma base que indica está ausente do catálogo —, a compilação é interrompida nessa falha da cadeia em vez de no mapeamento, porque um mapeamento não pode ser avaliado até que a cadeia de que depende seja resolvida. A verificação percorre a cadeia apenas através dos Components que já estão nesta máquina — os de um diretório de catálogo e os que a cache local de artefactos guarda sob um pin do lockfile — e nunca consulta um registo, pelo que uma base guardada apenas por um registo conta aqui como ausente. Obtê-la é o que faz aggrega pull: uma base é uma dependência de tudo o que a estende, pelo que um pull segue cada cadeia extends: que a Release alcança, obtém cada base que nenhum diretório de catálogo guarda e fixa-a no lockfile, onde a compilação seguinte a encontra. O Manifest não precisa de nenhuma linha para a própria base, a menos que um Aggregate também declare uma instância da base.
As sugestões de Recipe continuam mais restritas do que esta regra de correspondência. A lista de candidatos que um diagnóstico de mapeamento em falta imprime, e a ordenação que a conclusão automática do editor aplica a um valor de mapeamento, indicam as receitas que implementam o próprio tipo pedido; não se alargam a receitas que implementam uma das suas bases.
Para uma demonstração completa e executável — um wrapper publicado no catálogo, a única linha de Manifest que o consome, a Recipe da base a dar forma à sua saída renderizada, e a interrupção que uma instância do wrapper sem mapeamento próprio produz —, ver o exemplo completo examples/extends-wrapper/.
Consumo de versões entre entidades
Cada tipo de entidade do Aggrega — Component, Feature, Aggregate, Recipe, FeatureRecipe, Manifest, Release, Plugin, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary — contém um campo obrigatório metadata.version validado face à mesma regex SemVer (MAJOR.MINOR.PATCH segundo architecture/02-ecosystem-philosophy.md). As versões são uniformes na forma; o consumo das versões varia por tipo de entidade. Algumas versões participam ativamente na resolução; outras são proveniência descritiva face à qual o compilador não faz correspondência. A tabela abaixo abrange os tipos que não são bibliotecas, indicando o que o compilador faz com o campo de versão de cada entidade e usando a taxonomia de estado de quatro etiquetas de 10-status.md para classificar cada regime de consumo. Os quatro tipos de biblioteca ficam fora da tabela porque o seu regime é uniforme e diferente: um consumidor referencia uma biblioteca pelo nome simples, pode afirmar um mínimo de versão opcional :<version>, e o lockfile por Release detém a versão resolvida e o seu digest de conteúdo.
| Entidade | Regime de consumo | Estado |
|---|---|---|
| Component | Resolução de referências de tipo; correspondência de implements: da Recipe | available — formas exata, de intervalo caret (^MAJOR.MINOR.PATCH) e sem versão em ambos (ver Resolução de versões e Estado da linguagem → Correspondência de versões) |
| Feature | Resolução de referências de anexo; correspondência de implements: da FeatureRecipe | Igual a Component |
| Recipe | Resolução dos níveis de mapeamento do Manifest | available — formas exata, de intervalo caret e sem versão num valor de mapeamento, cada uma a selecionar a versão mais alta que a satisfaz |
| FeatureRecipe | Resolução dos níveis de mapeamento do Manifest | Igual a Recipe |
| Aggregate | Resolução da referência aggregates[].type do pai | available — formas exata, de intervalo caret e sem versão, cada uma a selecionar a versão mais alta que a satisfaz (ver Resolução de versões) |
| Plugin | Despacho do Provider através de recipe.spec.capability → spec.provider.capabilities | available — a capacidade simples seleciona o fornecedor, e um pin sobre ela (helm:<version>, helm:^<version>) seleciona que versão desse plugin renderiza; a identidade do plugin é a referência oci://<repository> sem digest mais metadata.version, e o digest de conteúdo fica registado no lockfile da release face ao qual a compilação verifica os bytes transferidos |
| Manifest | Proveniência do grafo IR (manifest_version) | available (lido apenas para a proveniência; nenhum papel no despacho da resolução) |
| Release | Proveniência do grafo IR (release_version) + metadados de template (.metadata.release_version) | Igual a Manifest |
Regimes de resolução do catálogo (Component, Feature, Aggregate, Plugin). Uma referência a um destes tipos — o type de um componente, o type de um anexo de funcionalidade, o aggregates[].type de uma importação de subagregado, o plugin de um passo de pipeline — é resolvida pela regra que Resolução de versões ensina: uma referência exata, de intervalo caret ou sem versão seleciona a versão mais alta que a satisfaz entre as que o catálogo contém, e o pull, a compilação, uma validação, o editor e as ferramentas destinadas ao assistente aplicam essa única regra da mesma forma. Para um Component ou uma Feature, a correspondência de implements: lê as mesmas três formas na direção oposta — uma versão concreta do tipo face à forma que uma Recipe ou uma FeatureRecipe declara — como a verificação de consistência descrita abaixo, não como uma seleção. O despacho para o plugin de renderização do Provider usa uma forma mais simples: procura pelo nome a recipe.spec.capability simples nas spec.provider.capabilities do plugin de renderização do fornecedor, e um pin de versão escrito sobre a capacidade seleciona que versão desse plugin renderiza, interrompendo quando nenhuma versão o satisfaz.
Resolução dos níveis de mapeamento do Manifest. O mecanismo de resolução plano mappings.{components,features} do Manifest (com os níveis name e type, o nome a prevalecer sobre o tipo, e o tipo com versão a prevalecer sobre o tipo sem versão) está documentado em entities/manifest.md. O resolvedor consome esses mapeamentos: a seleção de Recipe e de FeatureRecipe é uma pesquisa direta do valor de mapeamento no lockfile e no catálogo, e um componente ou um anexo cujo tipo não tenha mapeamento interrompe a compilação. spec.implements não seleciona uma Recipe — é a verificação de consistência no carregamento sobre um mapeamento que o autor já escreveu, e a origem da lista de candidatos que o diagnóstico de mapeamento em falta e a conclusão automática do editor oferecem. O despacho de capacidades parte então do campo spec.capability da Recipe resolvida, não da forma estrutural do Manifest.
Regimes de proveniência descritiva (Manifest, Release). O metadata.version do Manifest e o metadata.version da Release são lidos quando o compilador preenche a proveniência, e aparecem no bloco de proveniência do grafo IR como manifest_version e release_version; nenhuma etiqueta na saída renderizada contém qualquer um dos dois. Os templates também veem a versão da Release exposta como .metadata.release_version. Nenhuma das duas versões é comparada com a versão de outra entidade para o despacho da resolução; são pura proveniência.
Ler a tabela. A classificação de quatro etiquetas distingue «o campo de versão é aceite pelo esquema e existe na entidade» (sempre verdadeiro — regex SemVer uniforme) de «o compilador faz correspondência com esta versão durante a resolução» (varia por entidade).
Canalização entre pilares por ponte de esquema: ligar a intenção à infraestrutura
O Aggrega exprime uma forte separação de responsabilidades entre o Domínio 1 e o Domínio 4: o programador escreve a lógica cognitiva no bloco values, enquanto o operador dita o dimensionamento físico no bloco infra. O esquema Aggregate.yaml impõe um corolário concreto: a palavra-chave infra está ausente das instâncias de componente do Aggregate e dos seus anexos features e, combinada com additionalProperties: false, é rejeitada pela validação do esquema. Os programadores não devem ditar o dimensionamento físico dentro da intenção do programador; quando um valor específico se adequa ao caso da aplicação (por exemplo, uma porta fixada no código ou um número específico de CPU), o arquiteto pode expô-lo explicitamente na declaração schema: do Component, e o valor flui através de values.
Para os casos em que uma restrição de infraestrutura específica é parte intrínseca do contrato de um componente — uma base de dados de trading de alto débito que tem de ter 10 000 IOPS provisionadas, uma carga de trabalho de ML que tem de ser executada em exatamente 4 GPU —, os arquitetos de plataforma expõem a restrição através de um Component construído para esse fim, usando o padrão de canalização entre pilares por ponte de esquema.
O padrão de ponte de esquema para componentes conscientes da infraestrutura. O Component expõe o controlo de infraestrutura específico dentro do bloco values do programador através da sua declaração schema:, e o template valuesMapping: da Recipe associada canaliza o valor para a saída renderizada com a forma de infra:. O resultado é uma ponte tipada entre a intenção cognitiva e o dimensionamento físico: o programador dita a restrição de hardware através de um campo validado, e a restrição flui para Ops sem que nenhum dos lados escreva código de infraestrutura em bruto. O controlo é uma chave de pilar, pelo que é declarado no Component cujo contrato o detém — um Component que faz extends: de uma base não declara chaves de pilar e, por isso, não pode introduzir nenhuma.
# Domain 2: The Platform Catalog (the schema-bridge Component)apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/high-perf-postgres version: 1.0.0 labels: component.aggrega.ai/type: "stateful-server"spec: schema: values: # Expose the dial safely to the Developer with a typed contract. required_iops: { type: integer, min: 1000, max: 100000, required: true } infra: # Operator-owned sizing the Recipe below reads alongside the dial. storage: { size: { type: string, default: 100Gi } } compute: { instance_class: { type: string, default: db.m5.large } }# Domain 2: The Platform Catalog (the Recipe pipes the dial into provider infra)apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: aws-rds-high-perf-postgres version: 1.0.0spec: implements: core/high-perf-postgres:^1.0.0 capability: terraform source: ./modules/rds valuesMapping: | # The Recipe pipes the developer's values.required_iops into the provider's infra-side knob. iops: {{ .values.required_iops }} allocated_storage: "{{ .infra.storage.size }}" instance_class: "{{ .infra.compute.instance_class }}"# Domain 1: The Developer Intent (remains capability-agnostic)components: trading-db: type: core/high-perf-postgres:1.0.0 values: required_iops: 10000 # Developer dictates the hardware constraint safelyEscalamento multiambiente (o requisito de elevação de parâmetros). Para escalar esta restrição de hardware entre ambientes GitOps (Dev vs. Prod) sem alterar o Aggregate.yaml do programador, o programador eleva o valor para o contrato tipado parameters. Ops cumpre o requisito específico de IOPS através de ficheiros Release específicos de cada ambiente. A ordem de execução do compilador protege o fluxo: a validação do contrato de parâmetros é executada na resolução; a interpolação resolve o parâmetro na string values: circundante; o template valuesMapping: da Recipe canaliza o valor resolvido para a saída renderizada.
1. A intenção do programador (abstrair o controlo). O programador sabe que precisa de controlar as IOPS, mas abstrai o número explícito para o nível do ambiente através do contrato tipado parameters.
spec: parameters: env_iops: type: integer min: 1000 max: 100000 description: Provisioned IOPS for the trading-db instance components: trading-db: type: core/high-perf-postgres:1.0.0 values: required_iops: {{ .parameters.env_iops }} # Hoisted to the environment2. As Releases de GitOps (cumprimento por Ops). Ops cumpre o contrato parameters em ficheiros Release específicos de cada ambiente. O contrato tipado valida cada valor fornecido pela Release antes de a interpolação ser executada.
- Ambiente Dev (
release-dev.yaml):env_iops: 1000 - Ambiente Prod (
release-prod.yaml):env_iops: 25000
A ordem de compilação. Este mecanismo está protegido pela ordem de execução estrita do compilador na resolução:
- Validação do contrato de parâmetros. Cada valor de parâmetro fornecido pela Release é validado face à declaração tipada
parameters:do Aggregate. Um valor de Prod de25000é válido (dentro demin: 1000, max: 100000); um valor de500provocaria uma interrupção com um erro claro. - Interpolação. O compilador lê os valores de parâmetros da
Releasede Prod e interpola25000na string YAML doAggregateemvalues.required_iops. O mapa de parâmetros combinado permanece ativo durante a renderização para que as superfícies de template de caminho possam ler.parameters.<slot>diretamente; as superfícies de template de valor consomem o literal pós-interpolação já escrito no blocovalues:do Aggregate. O mapa permanece legível até que todas as fases de renderização estejam concluídas, e só é alcançável a partir da compilação para a qual foi resolvido. - Validação de esquema. A declaração
schema:do Component valida o dicionáriovalues:resultante;values.required_iops: 25000satisfaz omin: 1000, max: 100000do esquema. - Renderização do valuesMapping da Recipe. O template
valuesMapping:da Recipe associada canalizavalues.required_iopspara a saída com a forma deinfrado fornecedor (iops: 25000). O plugin Wasm do fornecedor gera a configuração física correta da base de dados. O programador obtém o seu controlo explícito do hardware, Ops obtém o seu escalamento específico de cada ambiente, e oAggregatemantém-se agnóstico em relação às capacidades.