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

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

As entidades do Aggrega referenciam umas às outras por meio de strings 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 inferindo o tipo de entidade a partir da posição no schema, e não de um sigilo ou prefixo. Autores que leem ou mantêm um arquivo YAML precisam ter em mente as regras de interpretação baseadas em posição para saber se core/postgres:1.0.0 se refere a um tipo de Component, um módulo Aggregate, uma Recipe, uma FeatureRecipe ou 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: versionadas e não versionadas 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 strings 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). Autores que precisam saber “o que o Aggrega faz com esta string?” devem encontrar a resposta aqui.

Inferência do tipo de entidade baseada em posição

A mesma string URI tem um significado de tipo de entidade diferente dependendo de onde aparece no schema. A tabela abaixo enumera cada posição em que o Aggrega espera um URI de referência a entidade, junto 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 — 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 o rótulo 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 (vinculaçã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 (vinculação granular de substituição)/featurerecipe/{provider}/{name}
Manifest.spec.mappings.features.annotations.<key>.featureFeature (vinculada 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 arquivo de Release, e nenhuma outra forma
Release.spec.aggregateAggregate (o destino de implantaçã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}

Três posições são listadas porque os autores recorrem a elas esperando um URI, e elas não são um. Um Manifest e uma Release são documentos do lado da implantação escritos lado a lado, e não entidades indexadas no catálogo, de modo 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 registro. O manifest: de uma Release nomeia um arquivo, ou o metadata.name simples de um Manifest situado ao lado da Release. Nas duas posições extends:, o valor nomeia um arquivo, e uma coordenada de registro escrita em qualquer uma delas é recusada, com a forma aceita nomeada no diagnóstico. As duas posições extends: também não são escritas da mesma forma — um Manifest também aceita o metadata.name simples de um Manifest situado ao lado da Release, enquanto uma Release aceita o caminho relativo e nada mais. Veja entities/release.md para a forma da Release e errors/fatal-halts.md para o que cada recusa diz.

A regra de inferência: a posição no schema YAML determina o tipo de entidade. Não há nenhum marcador de superfície (sigilo, prefixo, anotação no nível do schema) dizendo ao autor a que tipo de entidade um determinado campo type: faz referência. Os autores têm em mente as regras baseadas em 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 carrega nenhum sigilo de tipo (a seção anterior). Os URIs de Plugin são o contraponto deliberado: um URI de plugin de fato escreve um segmento classificador — seu tipo de socket — diretamente no caminho. As duas famílias de referências são lidas de forma diferente de propósito, e saber a qual família um URI pertence diz a você onde procurar sua classificação.

As coordenadas de Plugin são derivadas 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 vê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 registro (e do conjunto de plugins embutidos), de modo que o registro organiza os plugins por socket. Os plugins básicos são resolvidos para 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 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, veja entities/plugin.md.

As entidades de catálogo carregam o tipo nos metadados. A referência escrita é <publisher>/<category>/<name> (por exemplo, core/datastore/postgres). O kind: da entidade fica no arquivo; o tipo de entidade do URI é inferido da posição no schema, conforme Inferência do tipo de entidade baseada em posição acima. O caminho é organizado por categoria, não por tipo: um Component carrega um segmento de categoria (core/datastore/postgres); uma Recipe ou uma FeatureRecipe carrega 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.

Por que as duas formas diferem. Os Plugins são organizados no registro por socket, então o segmento do socket é a chave natural do registro e está presente em todo URI de plugin. As entidades de catálogo são organizadas no registro por categoria, então é a categoria — não o tipo — que o caminho escreve. Um URI, portanto, diz a você o socket de um plugin apenas pelo caminho, mas só diz o tipo de uma entidade de catálogo depois que você lê o arquivo (o tipo fica em metadata; a posição o fornece em um ponto de referência). Essa assimetria é intencional: o caminho de cada família espelha como essa família é organizada no registro, e não uma gramática única e uniforme imposta às duas.

Forma do URI — versionado vs. não versionado

Toda posição de URI acima aceita uma referência em uma de três formas — não versionada, ou fixada após dois-pontos com uma versão exata ou um intervalo com caret:

FormaExemploSemântica
Sem versãocore/postgresÉ resolvido para “qualquer versão” ou para “a mais recente registrada”, dependendo da 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 toda 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 após os últimos dois-pontos da referência, e somente quando esse texto não contém nenhuma /. Uma referência a um host de registro com porta — localhost:5000/core/postgres — portanto não carrega nenhuma fixação: o texto após os dois-pontos da porta continua a referência.

Uma fixação que não tem nenhuma dessas formas — um caret cujo texto não pode ser lido 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 nomeia versão alguma. Quando um comando resolve uma referência assim e ela não é resolvida, a recusa nomeia a referência, a fixação e as três formas acima, em vez de relatar uma entidade ou uma versão que o catálogo não contém; o diagnóstico é 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 ali, de modo que uma fixação malformada nunca muda quais referências são resolvidas, e uma fixação bem formada que nenhuma versão disponível satisfaz é relatada como tal. Nenhum schema define a gramática da fixação, então uma fixação malformada é relatada quando algo resolve a referência — aggrega validate, aggrega pull, aggrega build — e não quando o arquivo é carregado.

As formas coexistem na mesma posição. Os autores escolhem conforme precisem de fixação de 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 versionada vence a não versionada — uma chave versionada (core/api-server:1.0.0) tem precedência sobre a chave não versionada (core/api-server) quando ambas correspondem à mesma pesquisa. As duas variantes não são exclusivas; ambas podem ficar no mesmo mapa type: e o resolvedor escolhe a mais específica. O despacho do Provider decorre do campo spec.capability da Recipe resolvida, de modo que o Manifest mapeia um tipo para uma Recipe e nada mais.

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

Uma referência a um Component, uma Feature, um Aggregate ou um Plugin também aceita um intervalo com caret (core/postgres:^1.0.0) e, qualquer que seja a forma, seleciona a versão mais alta que a satisfaz entre as que o catálogo contém, por uma única regra que todo comando aplica — veja 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, veja 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: ela nomeia o que a entidade é, nunca onde ela está no momento.

A identidade é simples e sem host. Ela não carrega nenhum host de registro; o host é uma coordenada de resolução fornecida pela configuração por meio de default_registry e vinculada no momento da resolução. Mudar um registro de lugar, ou espelhar a mesma entidade em outro lugar, é uma mudança de configuração — as referências que nomeiam a entidade permanecem intactas.

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

No momento da resolução, o compilador une 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 é resolvida em relação a um registro diferente ou a uma versão fixada diferente sem nenhuma edição no código-fonte que a nomeia.

Inferência das formas abreviadas de URI OCI

Os autores não precisam 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 padrão

Todo URI sem domínio recebe como prefixo o default_registry configurado em .aggrega-config.yaml (padrã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 em três camadas

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

  1. Caminho local — para os documentos que uma Release e seu Manifest nomeiam. 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 arquivo 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 nomeiam nenhuma entidade e interrompem o build. Uma entidade escrita localmente é colocada em catalog/ na raiz do espaço de trabalho ou em um diretório que workspace.catalog_dirs lista, e é resolvida pelo nome por meio da camada do espaço de trabalho e do cache.
  2. Espaço de trabalho e cache — a pilha de busca do catálogo do espaço de trabalho, depois o cache. Os diretórios catalog_dirs: do espaço de trabalho de .aggrega-config.yaml — ou, para uma Release à qual a configuração dá diretórios próprios em workspace.releases, os dessa Release — são pesquisados na ordem escrita, e o diretório catalog/ da raiz do espaço de trabalho é pesquisado por último — depois de cada entrada listada, e somente 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 registro buscaram.
  3. Registro. Quando a camada do espaço de trabalho e do cache não encontra nada, as regras de inferência OCI se aplicam e a referência é buscada no registro remoto por aggrega pull, ou por um build executado com --auto-pull ou com a configuração auto_pull do espaço de trabalho; um build sem nenhum dos dois lê apenas o que seu lockfile fixa.

A cascata permite que um projeto misture os documentos que uma Release nomeia por caminho (a camada do caminho local) com conteúdo de catálogo copiado para o repositório e local ao espaço de trabalho (a camada do espaço de trabalho e do cache) e conteúdo do registro buscado remotamente (a camada do registro), e uma referência a uma entidade é escrita da mesma forma, qualquer que seja a das duas últimas camadas que contém a entidade.

Quando catalog_dirs: lista mais de um diretório, a lista é uma pilha de precedência ordenada em que o primeiro vence: uma identidade de entidade presente em mais de um diretório listado é resolvida para o diretório listado primeiro, e a ocorrência posterior é sombreada (substituída, não é um erro) — assim um projeto pode colocar seu próprio diretório de catálogo à frente de um compartilhado e substituir entidades pela identidade, enquanto o restante recai no compartilhado. A substituição é informada no detalhe da resolução. Dois arquivos que reivindicam a mesma identidade dentro de um único diretório continuam sendo 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, de modo que tudo o que um projeto lista prevalece sobre ele em uma colisão, e listar um diretório não relacionado nunca impede que ele seja lido. Ele é ignorado quando uma entrada listada já o alcança — a varredura de um diretório listado é recursiva, então uma pilha que nomeia 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 ainda lê catalog/; escrito como [], ele não lê nenhum catálogo local, e é assim que um espaço de trabalho diz 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) conforme as regras de consumo de versões próprias da posição. Veja 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 strings de formato

Além das strings URI, a superfície de autoria do Aggrega contém várias convenções distintas de strings de formato. Os autores que escrevem ou leem arquivos 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 registrado na inicialização do mecanismo 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 das etapas de pipeline: da FeatureRecipe; payloads JSONPatch de plugins WasmBase RFC 6901 conforme o contrato de plugins Wasm; declarada em plugins/plugin-contract.md
Regex SemVerCampos metadata.version em toda entidadeRegex 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 toda posição 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 sua própria condição — veja Forma do URI acima
Caminho do sistema de arquivosCaminhos relativos ao catálogo (por exemplo, entradas catalog_dirs: de .aggrega-config.yaml); caminhos de arquivo $import: da Recipe em workload: / artifacts: / valuesMapping:Lido como escrito na resolução — uma entrada catalog_dirs: relativa ao arquivo de configuração que a declara, um caminho $import: relativo ao próprio diretório da entidade; nenhum glob é expandido, então um * nomeia um arquivo ou diretório com esse nome
Expressão de seletor de rótulosComponent.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 de 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.capabilityBusca 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 sua própria gramática, seu próprio validador e sua própria forma de relatar erros. Os autores que encontram um erro de análise de uma string de formato leem a referência do respectivo formato para as regras de sintaxe.

O editor relata esses erros enquanto você escreve: aggrega serve valida cada documento que recebe em relação ao schema do seu tipo e retorna o mesmo veredito que um build daria (veja 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