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

Gramática de URI e inventário de cadeias de formato

As entidades do Aggrega referenciam-se umas às outras através de cadeias URI que aparecem em várias posições de autoria distintas. A mesma forma de URI (core/postgres:1.0.0) aparece em cinco ou mais contextos de tipo de entidade, com o compilador a inferir o tipo de entidade a partir da posição no schema e não de um sigilo ou prefixo. Os autores que leem ou mantêm um ficheiro YAML têm de ter presentes as regras de interpretação baseadas na posição para saber se core/postgres:1.0.0 se refere a um tipo de Component, a um módulo Aggregate, a uma Recipe, a uma FeatureRecipe ou a um plugin Wasm.

Esta página consolida a gramática de URI em todas as posições, as regras de precedência para chaves type: com e sem versão nos níveis de mapeamento do Manifest, as regras de inferência das formas abreviadas de URI OCI e o inventário mais amplo de cadeias de formato em todo o corpus (sintaxe de templates Go, funções Sprig, declarações JSON Schema 2020-12, JSONPath, padrões glob, regex SemVer). Os autores que precisem de saber «o que faz o Aggrega com esta cadeia?» devem encontrar aqui a resposta.

Inferência do tipo de entidade com base na posição

A mesma cadeia URI tem um significado de tipo de entidade diferente consoante o sítio onde aparece no schema. A tabela abaixo enumera cada posição em que o Aggrega espera um URI de referência a uma entidade, juntamente com o tipo de entidade inferido:

PositionTipo de entidade inferidoExpansão do caminho OCI
Aggregate.spec.components.<id>.typeComponent/component/{publisher}/{category}/{name}
Aggregate.spec.subsystems.<name>.components.<id>.typeComponent (igual a components — os subsistemas são agrupamentos de componentes)/component/{publisher}/{category}/{name}
Aggregate.spec.aggregates.<id>.typeAggregate (módulo de subagregado)/aggregate/{publisher}/{name}
Aggregate.spec.components.<id>.features.<id>.typeFeature/feature/{publisher}/{name}
Aggregate.spec.components.<id>.features.<id>.typeFeature (credencial — com a etiqueta feature.aggrega.ai/kind: secret)/feature/{publisher}/{name}
Manifest.spec.mappings.components.type.<key>Component (o URI usado como chave de pesquisa); o valor é um URI de Recipechave: /component/; valor: /recipe/{provider}/{name}
Manifest.spec.mappings.components.name.<id>Recipe (associação granular de substituição)/recipe/{provider}/{name}
Manifest.spec.mappings.features.type.<key>Feature (chave de pesquisa); o valor é um URI de FeatureRecipechave: /feature/; valor: /featurerecipe/{provider}/{name}
Manifest.spec.mappings.features.name.<id>FeatureRecipe (associação granular de substituição)/featurerecipe/{provider}/{name}
Manifest.spec.mappings.features.annotations.<key>.featureFeature (associada a uma anotação)/feature/{publisher}/{name}
Recipe.spec.implementsComponent (contrato de interface)/component/{publisher}/{category}/{name}
FeatureRecipe.spec.implementsFeature (contrato de interface)/feature/{publisher}/{name}
Component.spec.extends / Feature.spec.extendsComponent / Feature (pai na cadeia de herança)/component/{publisher}/{category}/{name} ou /feature/{publisher}/{name}
Manifest.spec.extendsManifest (pai na cadeia de herança de mapeamentos)não é uma posição de URI — um caminho relativo, ou o metadata.name simples de um Manifest ao lado da Release
Release.spec.extendsRelease (pai na cadeia de herança)não é uma posição de URI — um caminho relativo para um ficheiro de Release, e nenhuma outra forma
Release.spec.aggregateAggregate (o destino de implementação da Release)/aggregate/{publisher}/{name}
Release.spec.manifestManifest (o lockfile de mapeamento da Release)não é uma posição de URI — um caminho relativo, ou o metadata.name simples de um Manifest ao lado da Release
FeatureRecipe.spec.pipeline.<step>.pluginplugin Wasm/plugin/{pluginType}/{name}

São listadas três posições porque os autores recorrem a elas à espera de um URI, e não o são. Um Manifest e uma Release são documentos do lado da implementação escritos lado a lado, e não entidades indexadas no catálogo, pelo que nem o extends: de um nem o do outro, nem nenhum manifest: de uma Release, é resolvido em relação ao catálogo ou a um registo. O manifest: de uma Release indica um ficheiro, ou o metadata.name simples de um Manifest situado ao lado da Release. Nas duas posições extends:, o valor indica um ficheiro, e uma coordenada de registo escrita em qualquer uma delas é recusada, com a forma aceite indicada no diagnóstico. As duas posições extends: também não se escrevem da mesma forma — um Manifest aceita também o metadata.name simples de um Manifest situado ao lado da Release, enquanto uma Release aceita o caminho relativo e nada mais. Consulte entities/release.md para a forma da Release e errors/fatal-halts.md para o que diz cada recusa.

A regra de inferência: a posição no schema YAML determina o tipo de entidade. Não existe nenhum marcador de superfície (sigilo, prefixo, anotação ao nível do schema) que indique ao autor a que tipo de entidade se refere um determinado campo type:. Os autores têm presentes as regras baseadas na posição ao ler YAML; as ferramentas (o preenchimento automático do editor, aggrega inspect) leem as mesmas regras para apresentar sugestões específicas do tipo de entidade.

Duas formas de URI — plugins de coordenadas derivadas vs. entidades de catálogo com o tipo nos metadados

Um URI de entidade de catálogo não tem nenhum sigilo de tipo (a secção anterior). Os URIs de Plugin são o contraponto deliberado: um URI de plugin escreve de facto um segmento classificador — o seu tipo de socket — diretamente no caminho. As duas famílias de referências leem-se de forma diferente de propósito, e saber a que família pertence um URI indica onde procurar a sua classificação.

As coordenadas de Plugin derivam do tipo do plugin. Uma referência de plugin é oci://hub.aggrega.ai/plugin/<pluginType>/<name>. A coordenada é derivada: o segmento <pluginType> e o <name> simples provêm do bloco de endereçamento do plugin — metadata.pluginType e metadata.name — compostos no caminho. O socket não é codificado como caminho no nome; metadata.name é simples. A coordenada derivada É a chave do registo (e do conjunto de plugins incorporados), pelo que o registo organiza os plugins por socket. Os plugins de base resolvem-se em coordenadas como plugin/provider/helm, plugin/linter/publishing e plugin/parser/yaml — cada uma a composição de um metadata.name simples (helm, publishing, yaml) com o seu metadata.pluginType (provider, linter, parser). O segmento <pluginType> é exatamente o tipo de socket do plugin: o mesmo <name> simples sob um pluginType diferente é um plugin diferente, porque a coordenada derivada — e, portanto, a identidade — difere. Para a taxonomia completa de sockets segundo a qual o segmento <pluginType> classifica, consulte entities/plugin.md.

As entidades de catálogo têm o tipo nos metadados. A referência escrita é <publisher>/<category>/<name> (por exemplo, core/datastore/postgres). O kind: da entidade está no ficheiro; o tipo de entidade do URI é inferido da posição no schema, conforme Inferência do tipo de entidade com base na posição acima. O caminho organiza-se por categoria, não por tipo: um Component tem um segmento de categoria (core/datastore/postgres); uma Recipe ou uma FeatureRecipe tem a sua capacidade de renderização como primeiro segmento (helm/postgres); os tipos restantes são planos, <publisher>/<name>. Nada no caminho escreve o tipo de entidade.

Porque diferem as duas formas. Os Plugins estão organizados no registo por socket, pelo que o segmento do socket é a chave natural do registo e está presente em todos os URIs de plugin. As entidades de catálogo estão organizadas no registo por categoria, pelo que é a categoria — não o tipo — que o caminho escreve. Um URI indica, portanto, o socket de um plugin apenas a partir do caminho, mas só indica o tipo de uma entidade de catálogo depois de lido o ficheiro (o tipo está em metadata; a posição fornece-o num ponto de referência). Esta assimetria é intencional: o caminho de cada família espelha a forma como essa família está organizada no registo, e não uma gramática única e uniforme imposta a ambas.

Forma do URI — com versão vs. sem versão

Todas as posições de URI acima aceitam uma referência numa de três formas — sem versão, ou fixada após dois pontos com uma versão exata ou um intervalo com caret:

FormaExemploSemântica
Sem versãocore/postgresResolve-se em «qualquer versão» ou em «a mais recente registada», consoante a semântica de resolução da posição
Fixação exatacore/postgres:1.0.0Fixa uma versão específica. A versão é uma versão semântica, a forma que o metadata.version de cada entidade assume
Fixação com caretcore/postgres:^1.0.0Seleciona a versão mais alta compatível com a indicada — para ^1.0.0, igual ou superior a 1.0.0 e inferior a 2.0.0

A fixação é o texto a seguir aos últimos dois pontos da referência, e apenas quando esse texto não contém nenhuma /. Uma referência a um host de registo com porta — localhost:5000/core/postgres — não tem, portanto, nenhuma fixação: o texto a seguir aos dois pontos da porta continua a referência.

Uma fixação que não tem nenhuma destas formas — um caret cujo texto não se lê como um intervalo de versões (core/postgres:^garbage), ou uma fixação exata que não é uma versão semântica (core/postgres:1.x, core/postgres:1.0, core/postgres:v1.0.0) — não indica versão nenhuma. Quando um comando resolve uma referência destas e esta não se resolve, a recusa indica a referência, a fixação e as três formas acima, em vez de reportar uma entidade ou uma versão que o catálogo não contém; o diagnóstico está descrito em errors/fatal-halts.md em «A version pin is none of the forms a pin takes (Uma fixação de versão não tem nenhuma das formas que uma fixação assume)». A fixação só é avaliada aí, pelo que uma fixação malformada nunca altera que referências se resolvem, e uma fixação bem formada que nenhuma versão disponível satisfaz é reportada como tal. Nenhum schema define a gramática da fixação, pelo que uma fixação malformada é reportada quando algo resolve a referência — aggrega validate, aggrega pull, aggrega build — e não quando o ficheiro é carregado.

As formas coexistem na mesma posição. Os autores escolhem consoante precisem de fixar a versão ou de flexibilidade de versão. O nível mappings.{components,features}.type do Manifest suporta ambas as variantes como chaves de dicionário distintas, com a precedência a chave com versão ganha à chave sem versão — uma chave com versão (core/api-server:1.0.0) tem precedência sobre a chave sem versão (core/api-server) quando ambas correspondem à mesma pesquisa. As duas variantes não são exclusivas; ambas podem estar no mesmo mapa type: e o resolvedor escolhe a mais específica. O despacho do Provider decorre do campo spec.capability da Recipe resolvida, pelo que o Manifest mapeia um tipo para uma Recipe e nada mais.

Para o regime de consumo de versões por entidade (que entidades têm efetivamente o seu campo de versão consumido pelo despacho de resolução e quais o usam como proveniência descritiva), consulte vocabulary/inheritance-and-interface.md «Cross-entity version consumption (Consumo de versões entre entidades)».

Uma referência a um Component, a uma Feature, a um Aggregate ou a um Plugin aceita também um intervalo com caret (core/postgres:^1.0.0) e, seja qual for a sua forma, seleciona a versão mais alta que a satisfaz entre as que o catálogo contém, segundo uma única regra que todos os comandos aplicam — consulte version-resolution.md. Para a correspondência de três formas de implements:, que é a verificação de consistência de um mapeamento e não uma seleção, consulte 10-status.md «Version matching (Correspondência de versões)».

Identidade, não localização

Uma referência canónica a uma entidade — incluindo uma referência de plugin — é uma identidade, não uma localização: indica o que a entidade é, nunca onde se encontra atualmente.

A identidade é simples e sem host. Não tem nenhum host de registo; o host é uma coordenada de resolução fornecida pela configuração através de default_registry e associada no momento da resolução. Mudar um registo de sítio, ou espelhar a mesma entidade noutro lado, é uma alteração de configuração — as referências que indicam a entidade ficam intactas.

A identidade é também sem versão. Uma referência pode ter uma fixação de versão opcional (:<version> ou :^<version>) para restringir que versões a satisfazem, e cada Release regista a versão exata resolvida como fixação no seu lockfile, mas a versão é fornecida ao lado da identidade em vez de nela incorporada.

No momento da resolução, o compilador junta a identidade simples ao host configurado e à versão fixada para chegar a bytes concretos. Como ambos são fornecidos separadamente, a mesma referência resolve-se face a um registo diferente ou a uma versão fixada diferente sem nenhuma edição na fonte que a indica.

Inferência das formas abreviadas de URI OCI

Os autores não têm de escrever cada URI como um URI OCI totalmente qualificado. O compilador aplica quatro regras de inferência ortogonais para expandir as formas abreviadas de autoria em URIs OCI canónicos no momento da resolução. As regras:

Regra 1 — Domínio predefinido

A qualquer URI sem domínio é anteposto o default_registry configurado em .aggrega-config.yaml (predefinição: hub.aggrega.ai/).

# Shorthand
type: core/postgres:1.0.0
# Equivalent canonical form
type: hub.aggrega.ai/component/core/postgres:1.0.0

Regra 2 — Expansão contextual da entidade

O compilador acrescenta o segmento de tipo de entidade correto com base na posição no schema. O mapeamento é o mesmo da tabela de inferência por posição acima (/component/, /aggregate/, /recipe/, /featurerecipe/, /feature/, /plugin/).

# Same string, two positions, two expansions
Aggregate.spec.components.foo.type: core/postgres:1.0.0
# → hub.aggrega.ai/component/core/postgres:1.0.0
Manifest.spec.mappings.components.type."core/postgres:1.0.0": helm/postgres:1.0.0
# Key: hub.aggrega.ai/component/core/postgres:1.0.0
# Value: hub.aggrega.ai/recipe/helm/postgres:1.0.0

Regra 3 — Precedência de três níveis

Antes de aplicar a inferência OCI, o compilador resolve o URI através do modelo de resolução de entidades em três níveis documentado em architecture/13-catalog-and-registry.md:

  1. Caminho local — para os documentos que uma Release e o seu Manifest indicam. O aggregate, o manifest ou o extends de uma Release, ou o extends de um Manifest, escritos com um prefixo ./ ou ../, são lidos como um ficheiro relativo ao próprio diretório da Release; a inferência OCI não é executada. Nenhuma outra posição aceita um caminho: um type, uma chave ou um valor de mapeamento do Manifest, um implements ou um plugin de pipeline escritos como ./… não indicam nenhuma entidade e interrompem o build. Uma entidade escrita localmente é colocada em catalog/ na raiz do espaço de trabalho ou num diretório que workspace.catalog_dirs lista, e resolve-se pelo nome através do nível do espaço de trabalho e da cache.
  2. Espaço de trabalho e cache — a pilha de pesquisa do catálogo do espaço de trabalho, depois a cache. Os diretórios catalog_dirs: do espaço de trabalho de .aggrega-config.yaml — ou, para uma Release à qual a configuração atribui diretórios próprios em workspace.releases, os dessa Release — são pesquisados pela ordem escrita, e o diretório catalog/ da raiz do espaço de trabalho é pesquisado em último lugar — depois de cada entrada listada, e apenas quando esse diretório existe. Uma correspondência em qualquer ponto da pilha interrompe a inferência OCI. Uma falha consulta então artifact_cache_dir, que guarda o que pulls anteriores do registo obtiveram.
  3. Registo. Quando o nível do espaço de trabalho e da cache não encontra nada, aplicam-se as regras de inferência OCI e a referência é obtida do registo remoto por aggrega pull, ou por um build executado com --auto-pull ou com a definição auto_pull do espaço de trabalho; um build sem nenhum dos dois lê apenas o que o seu lockfile fixa.

A cascata permite a um projeto combinar os documentos que uma Release indica por caminho (o nível do caminho local) com conteúdo de catálogo incorporado e local ao espaço de trabalho (o nível do espaço de trabalho e da cache) e com conteúdo do registo obtido remotamente (o nível do registo), e uma referência a uma entidade escreve-se da mesma forma, seja qual for o dos dois últimos níveis que contém a entidade.

Quando catalog_dirs: lista mais do que um diretório, a lista é uma pilha de precedência em que o primeiro ganha, ordenada: uma identidade de entidade presente em mais do que um diretório listado resolve-se no diretório listado primeiro, e a ocorrência posterior é sombreada (substituída, sem ser um erro) — assim, um projeto pode colocar o seu próprio diretório de catálogo à frente de um partilhado e substituir entidades pela identidade, enquanto as restantes recaem sobre o partilhado. A substituição é reportada no detalhe da resolução. Dois ficheiros que reclamem a mesma identidade dentro de um único diretório continuam a ser um erro de autoria que interrompe o carregamento.

O diretório catalog/ da raiz do espaço de trabalho fica no fim dessa pilha e não no topo, pelo que tudo o que um projeto lista prevalece sobre ele numa colisão, e listar um diretório não relacionado nunca impede que seja lido. É ignorado quando uma entrada listada já o alcança — o percurso de um diretório listado é recursivo, pelo que uma pilha que indica a raiz do espaço de trabalho já o leu. Omitir catalog_dirs: e escrevê-lo como lista vazia são declarações diferentes: omitido, o espaço de trabalho continua a ler catalog/; escrito como [], não lê nenhum catálogo local, e é assim que um espaço de trabalho declara que não tem nenhum.

Regra 4 — Tratamento da versão

Um URI pode incluir ou omitir o segmento de versão. O tratamento da versão depende da posição de resolução (resolução do nível do Manifest, correspondência de implements:, importação de subagregados) segundo as regras de consumo de versões próprias da posição. Consulte inheritance-and-interface.md «Cross-entity version consumption (Consumo de versões entre entidades)» para a semântica de versões por entidade.

Inventário de cadeias de formato

Para além das cadeias URI, a superfície de autoria do Aggrega contém várias convenções distintas de cadeias de formato. Os autores que escrevem ou leem ficheiros YAML encontram os seguintes formatos em posições diferentes:

FormatoOnde é escritoValidado por
Template Go ({{ .field }})Recipe valuesMapping: / workload: / artifacts: / provides: / locals: / source:; FeatureRecipe injectMapping: / with: de pipeline; interpolação de parameters: no Aggregate; Release directory: / subDirectory:Parser de templates Go no momento da avaliação; regras de disponibilidade por local em templates/expansion-matrix.md
Referência de funções Sprig ({{ default 1 .v }} etc.)As mesmas superfícies dos templates GoFuncMap do Sprig v3 registada na inicialização do motor de templates; lista completa de helpers em templates/sprig-functions.md
JSON Schema 2020-12 (forma compacta ou completa)Conteúdo schema: de Component / Feature (ou um $ref: para uma entrada de uma SchemaLibrary)Validador JSON Schema no carregamento da entidade durante a resolução
JSON Pointer (RFC 6901)Chaves locals.<*_path>: da Recipe (volumes_path, containers_path etc.); referências à saída dos passos de pipeline: da FeatureRecipe; payloads JSONPatch de plugins WasmBase RFC 6901 segundo o contrato de plugins Wasm; declarada em plugins/plugin-contract.md
Regex SemVerCampos metadata.version em todas as entidadesRegex JSON Schema ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-...)?$ por schema de entidade
Fixação de versão (:<version>, :^<version>)O segmento de versão de uma referência a uma entidade, em todas as posições de URI acimaO compilador, quando resolve a referência: uma fixação exata é uma versão semântica e o intervalo de uma fixação com caret é analisado, e uma fixação malformada é recusada sob a sua própria condição — consulte Forma do URI acima
Caminho do sistema de ficheirosCaminhos relativos ao catálogo (por exemplo, entradas catalog_dirs: de .aggrega-config.yaml); caminhos de ficheiro $import: da Recipe em workload: / artifacts: / valuesMapping:Lido tal como está escrito na resolução — uma entrada catalog_dirs: relativa ao ficheiro de configuração que a declara, um caminho $import: relativo ao próprio diretório da entidade; nenhum glob é expandido, pelo que um * indica um ficheiro ou diretório com esse nome
Expressão de seletor de etiquetasComponent.spec.usesSchema.<socket>.selector; appliesTo: / appliesToAnyOf: da FeatureParser de seletores do Aggrega onde o seletor é avaliado; gramática de seletores documentada em vocabulary/modifier-system.md
Forma da chave de anotação (<namespace>/<name>)Chaves metadata.annotations; chaves features.annotations do Manifest; cascata de anotações da fronteiraRegex JSON Schema por entidade; disciplina dos prefixos reservados em vocabulary/labels-and-annotations.md
Nome do Provider, opcionalmente com fixação de versão (helm, helm:^1.0.0)Recipe.spec.capability; FeatureRecipe.spec.capabilityPesquisa de despacho do Provider; uma fixação que nenhuma versão de plugin satisfaz interrompe o build
Chave de entrega de inject (env.<KEY>, file.<path>, arg.<flag>)Blocos inject: do Aggregate; saída de injectMapping: da FeatureRecipeSchema de inject em vocabulary/topology-triad.md

Cada formato tem a sua própria gramática, o seu próprio validador e a sua própria forma de reportar erros. Os autores que encontram um erro de análise de uma cadeia de formato leem a referência do respetivo formato para as regras de sintaxe.

O editor reporta estes erros durante a escrita: aggrega serve valida cada documento que recebe face ao schema do seu tipo e devolve o mesmo veredicto que um build daria (consulte cli/aggrega-serve.md «Live validation (Validação em tempo real)»), e aggrega scaffold cria o rascunho de um documento inicial de qualquer tipo.

Referências cruzadas