aggrega pull
aggrega pull resolve todas as dependências de uma Release e grava um lockfile que fixa cada dependência em uma versão e um digest de conteúdo exatos. Um aggrega build posterior usa o que o lockfile fixa, verifica-o e é interrompido nomeando qualquer coisa de que precise e que não esteja fixada ali — assim as builds são reproduzíveis e podem funcionar offline.
Tudo o que uma build consome é fixado neste único momento. As entidades do catálogo, os artefatos de origem para os quais uma Recipe aponta um provider e os documentos remotos que um provider solicita durante a renderização são resolvidos pelo mesmo comando e registrados na mesma gravação do lockfile. aggrega pull é a etapa que acessa a rede; a build não. Essa é a regra inteira, e o restante desta página é o que decorre dela.
O que ele faz
aggrega pull resolve três tipos de dependência em uma única passagem:
- Entidades do catálogo — os Components, Features, Recipes, FeatureRecipes, bibliotecas de schemas e de mapeamentos e plugins Wasm que a Release referencia, resolvidos de forma transitiva (por meio de
extends:,implements:,aggregate:, vinculações de Feature e pontos$import:/$ref:das bibliotecas) e obtidos do registry quando ainda não estão disponíveis localmente. - Artefatos de origem — a
source:remota para a qual uma Recipe ou FeatureRecipe específica direciona um provider: um chart do Helm (OCI ou HTTPS clássico) ou um fragmento do Compose via HTTPS. Cada um é obtido, armazenado em cache e fixado. - Entradas externas — os documentos remotos que um provider solicita ao host durante a renderização, como um
$refnovalues.schema.jsonde um chart que aponta para uma URL. Cada uma é obtida, armazenada sob seu digest de conteúdo e fixada.
Dois dos três são lidos dos documentos que você escreveu. O terceiro não: as entradas externas são encontradas renderizando a Release, e é por isso que este comando faz uma renderização. Executar o comando não exige nada disso — Como a resolução encontra as entradas externas explica isso por completo, junto com o custo da renderização, o que acontece quando ela não pode ser concluída e como um build que preenche o próprio lockfile se relaciona com ela.
Uma entidade do catálogo nomeada sem registry é obtida por meio do default_registry do workspace, e um caminho de repositório que esse padrão contenha é o local de onde ela é obtida. Com default_registry: ghcr.io/acme, core/api-server é obtido de ghcr.io/acme/component/core/api-server — onde aggrega push o publica por meio do mesmo padrão — e é lá que sua assinatura é procurada. O caminho indica apenas a localização: a assinatura que um pull exige, as chaves e identidades em que ele confia e a credencial que apresenta são as mantidas para o host, de modo que a entrada registries para ghcr.io rege todos os caminhos nesse host. O lockfile registra uma entidade assim por sua identidade, versão e digests, assim como registra uma obtida apenas de um host. A grafia de um caminho é descrita em como um host de registry é escrito.
O comando grava o resultado em <release-stem>.lock ao lado da Release. Um workspace que vincula um plugin que retorna um veredito de aceitação ou rejeição também ganha um segundo arquivo nesse diretório — o registro de confiança de plugins.
Um pull ao qual se pede para fixar grava mais um tipo de arquivo. Ao lado de cada Recipe e FeatureRecipe nos seus diretórios de catálogo que importa um arquivo de artefato, aponta para uma source: remota que você escreveu por completo ou lê uma source: ao lado dela, fica um entity.lock que registra o digest desse conteúdo. Registrá-lo é a etapa do autor da entidade, aggrega pin, e por padrão um pull não a executa: ele confronta o lock de cada uma dessas entidades com o que a etapa registraria e é interrompido onde falta um pin. aggrega pull --pin-sources, ou um workspace que define pin_sources_at_pull: true, executa a etapa em vez disso — e então o efeito de um pull vai além do diretório em que está a Release, embora os arquivos de entidade que você escreveu nunca sejam gravados. O lock da entidade descreve esse arquivo, e Pré-visualizar o que um pull gravaria mostra o conjunto completo para o seu workspace antes que qualquer coisa mude.
Um pull recusado porque uma referência não foi resolvida para nada informa de onde as entidades locais são lidas, onde quer que seja executado. A recusa traz o relato do próprio workspace sobre os diretórios de onde leu entidades locais e sobre o que mudar para que a entidade seja lida — a nota que De onde as entidades locais são lidas mostra — e o traz a partir deste comando, de um build que resolve primeiro suas dependências, da ferramenta de pull do aggrega mcp e igualmente da resolução de dependências de um editor, porque é a resolução que todos eles executam que o compõe. A recusa da ferramenta de pull também informa o código curto e o código descritivo da condição, assim como um terminal imprime o código curto no início da recusa. Um arquivo nesses diretórios que declara uma apiVersion do Aggrega — uma linha que começa, sem recuo, com apiVersion: e um valor que começa com aggrega.ai/ — e que não pôde ser carregado, por exemplo um que não pode ser analisado como YAML, é nomeado na mesma recusa, entre os arquivos de catálogo ignorados no carregamento, com o motivo dado pelo próprio analisador: esse arquivo pode ser o que declara a entidade que a referência nomeia, e nada pode ser lido nele que diga qual entidade ele declara. Um arquivo YAML que declara outra apiVersion, ou nenhuma, não é um documento do Aggrega e nunca é nomeado ali.
O lockfile
O lockfile fixa cada dependência em seu URI, versão resolvida e digest de conteúdo. Ele tem seções para entidades do catálogo, bibliotecas de schemas e de mapeamentos (cada uma com referências de volta para os Components e Features que a consomem), plugins Wasm, artefatos de origem, entradas externas (cada uma indexada por URL e com os plugins que a solicitaram) e os próprios arquivos da Release. O arquivo é gravado em uma forma canônica e determinística.
Uma entidade é registrada pelo que uma publicação dela contém. O digest na linha de uma entidade abrange seu documento e cada arquivo que ela nomeia ao seu lado — a source: local de uma Recipe ou FeatureRecipe, cada arquivo que um $import: nomeia, o entity.lock ao lado dela, cada arquivo de schema que um Component ou uma Feature importa — o mesmo conjunto que aggrega push publica. Cada arquivo contribui com seu caminho e seus bytes, e nada mais contribui: nem a forma como um arquivo compactado foi comprimido, nem um carimbo de data/hora, nem um bit de permissão, incluindo o bit de execução. Uma entidade que não nomeia nenhum arquivo é registrada como esse único documento. Assim, a mesma entidade registra o mesmo digest seja lida do seu diretório de catálogo ou obtida de um registry, e um lockfile commitado a partir de um checkout é verificado em outro checkout do mesmo commit qualquer que seja seu umask, e independentemente de o sistema desse checkout registrar quais arquivos são executáveis. Um chart editado sob uma Recipe, um arquivo adicionado a uma origem que ela declara e um entity.lock alterado mudam cada um o digest; um script cujo bit de execução foi invertido, e uma nota ao lado da entidade que nada nomeia, não. O Aggregate e o Manifest que a Release nomeia são registrados da mesma forma, cada um como seu único documento. Uma biblioteca é registrada pelo digest de seus bytes, que são seu documento onde quer que seja lida.
Cada Recipe e FeatureRecipe que o Manifest associa é uma linha, qualquer que seja o nível que a associa. Uma realização que o nível name do Manifest escolhe para uma única instância ou uma única vinculação é adquirida e registrada exatamente como uma que seu nível type escolhe para cada instância de um tipo, e o campo referenced_from da sua linha nomeia a entrada que a associa — manifest.spec.mappings.components.name.<instance> ou manifest.spec.mappings.features.name.<attachment>. Um build a confronta com essa linha, de modo que um lockfile que não a registra interrompe o build, nomeando a realização e essa entrada. Consulte Mapeamento plano de URI para os dois níveis.
As vinculações de uma conexão são dependências exatamente como as de um componente. A Feature que uma vinculação em uma conexão nomeia — escrita em uma entrada uses: de um componente no Aggregate, ou em uma entrada de conexão na Release — é adquirida e registrada como a Feature de uma vinculação escrita no próprio componente, e o campo referenced_from da sua linha nomeia a entrada de conexão que o autor escreveu, terminando em .uses.<socket>.<alias>.features.<slot>.type. A realização que o Manifest associa a ela também é uma linha, seja features.type que a associe ou features.name indexado pelo nome da vinculação, <alias>.<slot>. Um build confronta ambas com suas linhas: um lockfile sem uma delas interrompe o build nomeando a referência e a entrada que a solicita, e uma Feature cujo conteúdo mudou desde o pull o interrompe nomeando ambos os digests. Consulte a entrada de conexão do Aggregate para a vinculação em si.
Uma base que um Component ou uma Feature estende é uma linha, quer algo mais a nomeie ou não. O pull segue cada extends: até o fim de sua cadeia e registra cada base sob seu próprio tipo de entidade, com o referenced_from de sua linha nomeando o spec.extends da entidade que a estende — component(<name>:<version>).spec.extends. Um build lê a base dessa linha, então um Manifest mapeia o tipo próprio de um wrapper e não precisa de nenhuma linha para a base dele. Uma base que nenhum diretório de catálogo, cache ou registry contém é relatada onde a cadeia é mesclada — consulte An extends: chain cannot be assembled (Não é possível montar uma cadeia).
A Release é registrada pelo seu conteúdo, não só pelo seu nome. Tudo o que a Release solicita — para qual versão de chart uma origem é resolvida, quais componentes vão parar em qual fronteira — é resolvido a partir do que o arquivo contém, por isso release_documents registra o digest da Release e de cada Release que ela estende, ao lado de release, que a nomeia. Edite a Release depois do pull e o build seguinte é interrompido antes de qualquer renderização, nomeando o arquivo que você editou e pedindo que você faça o pull novamente; um simples aggrega pull --release <release> registra a edição respeitando todos os outros pins. O digest abrange os bytes do arquivo como estão, então uma mudança em um comentário ou em espaços também conta, exatamente como para o Aggregate e o Manifest. Um arquivo que a Release importa por meio de parameters não é registrado dessa forma.
Um pull procura um marcador de descontinuação em cada artefato cuja assinatura verifica, e informa o que encontrou. Um marcador cuja própria assinatura é verificada em relação a um signatário que o pull aceita — o próprio signatário do artefato, ou uma identidade em trusted_deprecation_identities do registry — é registrado e anunciado com sua severidade e o signatário do marcador. Um marcador que o pull encontrou e não pôde aceitar — ilegível, não assinado, assinado por alguém em quem a política não confia, ou com uma assinatura que não pôde ser verificada — é informado como marker present but not honored, com o motivo, e não é registrado. Uma consulta que não pôde ser concluída — o pull não conseguiu abrir o registry do artefato, ou a listagem do que está anexado a ele não respondeu — é informada como marker lookup did not complete, com o motivo, e não registra nada, porque o pull não descobriu nada sobre a existência de um marcador. Em um registry cuja própria política de confiança exige uma assinatura para o tipo do artefato e não é advisory, qualquer um desses dois casos interrompe o pull em vez de ser informado. Um artefato sem marcador não produz nenhuma linha, e onde a verificação de assinaturas está desativada, para o espaço de trabalho ou para o registry do artefato, nenhum marcador é procurado.
Faça commit de <release-stem>.lock junto com a Release, como você faz commit de qualquer manifesto de dependências fixadas. Um diff do lockfile mostra aos revisores exatamente quais versões e digests de dependências mudaram; uma mudança no digest de uma biblioteca nomeia os consumidores afetados.
O que um determinado pull fez — se cada entidade foi obtida do zero de um registry (fetched-fresh), reutilizou um slot do cache (cache-reuse), foi encontrada em um catálogo local (local), foi servida a partir da cópia embutida no binário do compilador (in-binary) ou era externa (external: o Aggregate ou o Manifest da própria Release, lidos do arquivo ou da entrada que a Release nomeia em vez de resolvidos como uma de suas dependências; um Aggregate que o pull obteve de um registry é, nesse caso, fetched-fresh) — é um diagnóstico transitório do evento de pull impresso em stdout por --detail, e nunca é gravado no lockfile. Qual origem serviu uma entidade depende do estado local da máquina que faz o pull, então persistir isso quebraria a identidade byte a byte do lockfile entre máquinas. Ele informa o que este pull fez, o que é irrecuperável depois (uma entidade recém-obtida é armazenada em cache pela execução seguinte); para o estado de resolução pós-pull das dependências de uma Release, use aggrega inspect.
O lock da entidade
Uma Recipe ou FeatureRecipe pode depender de bytes fora do seu próprio documento: um chart ou fragmento obtido de uma source: remota, um arquivo que uma entrada artifacts — ou uma entrada do boundary.artifacts de uma Recipe — traz com $import, ou os arquivos de uma source: que nomeia um diretório ou um arquivo ao lado dela. O digest de cada um deles é registrado em um arquivo chamado entity.lock, no mesmo diretório do arquivo da entidade. O arquivo de entidade que você escreveu nunca é gravado; o que foi derivado fica ao lado dele. O schema do lock da entidade descreve o arquivo campo a campo.
Quem o grava. Uma única etapa o grava: aggrega pin, que o autor da entidade executa, não precisa de nenhuma Release e registra todas as classes de pin que o lock contém. aggrega pull --pin-sources e aggrega push --pin-sources executam essa mesma etapa em nome do autor e gravam os mesmos bytes. Um pull ao qual não se pediu para fixar não grava lock nenhum: para cada Recipe e FeatureRecipe que a Release constrói a partir dos seus diretórios de catálogo, ele compara o que a etapa registraria com o que o lock contém, e é interrompido onde um pin falta ou não corresponde mais à sua entrada, nomeando a entidade, cada entrada e sua classe, e aggrega pin. Os arquivos de uma origem local são confrontados com seus pins como um único conjunto: um lock que não registra nenhum deles interrompe o pull, assim como um arquivo adicionado, alterado ou removido desde o pin. A chave de workspace pin_sources_at_pull torna a fixação o padrão de todo pull, e --pin-sources=false restaura a interrupção para uma execução. A fixação é um dever de autoria, então uma interrupção no primeiro pull de um consumidor significa que quem publicou a entidade nunca a fixou; o remédio do consumidor é essa chave, e não uma edição manual do diretório de outra pessoa. aggrega pin explica isso por completo.
O que ele contém. Três listas, cada linha nomeando uma entrada:
sourceDigests— uma linha para cadasource:remota cujas coordenadas você escreveu por completo, sem template emkind,url,chart,module_subdir,versionouref. A linha traz okinde aurlda origem, seuchartoumodule_subdirquando houver, a versão para a qual ela foi resolvida — para uma origem git, o commit que seurefnomeava — e o digest de conteúdo do arquivo compactado obtido, além do digest do manifesto para um chart obtido via OCI.artifactDigests— uma linha para cada entradaartifactsouboundary.artifactsfornecida por um arquivo importado com$import, nomeando a entrada e o digest dos bytes do arquivo. Uma entradaartifactsé nomeada por sua chave, e uma entradaboundary.artifactscomoboundary/<key>, de modo que uma entrada de cada bloco escrita sob a mesma chave é fixada separadamente.localSourceDigests— uma linha para cada arquivo com que umasource:que nomeia um diretório ou um arquivo ao lado da entidade contribui para o que uma publicação da entidade contém, nomeando o caminho do arquivo ao lado da entidade e o digest de seus bytes. Nada é obtido para uma origem assim; o digest de seus arquivos é calculado como eles estão. Uma origem escrita como template contribui com todos os arquivos do diretório da entidade, então cada um deles tem uma linha.
O que ele não contém:
- Uma origem remota cujas coordenadas são preenchidas a partir de um template — uma
versionlida de.infra, por exemplo. Qual artefato ela nomeia é decidido por cada Release que usa a entidade, então cada versão para a qual ela é resolvida é fixada no lockfile dessa Release, e nada sobre ela é gravado ao lado da entidade. - Uma entrada
artifactsouboundary.artifactsinline, que faz parte do arquivo da entidade, e uma entrada tirada de uma ArtifactLibrary, cujo conteúdo é fixado pela versão da biblioteca que o lockfile registra.
Uma entidade sem nada a fixar não recebe nenhum entity.lock, e a etapa, executada sobre uma entidade que não precisa mais dele, o remove.
Faça commit dele ao lado da entidade. Cada Recipe e FeatureRecipe usa o mesmo nome de arquivo, e o diretório em que ele está indica a qual entidade pertence, então o lock acompanha esse diretório. Ele não traz carimbo de data/hora e suas linhas são mantidas em uma ordem fixa, então a etapa sobre entradas inalteradas o deixa idêntico byte a byte, e um diff sobre ele nomeia a origem, o arquivo importado ou o arquivo da origem local que mudou. Um diretório contém um único lock, então a etapa recusa uma Recipe ou FeatureRecipe com qualquer outra entidade ao lado — cada tipo tem seu próprio diretório, exceto Aggregate, Release e Manifest — e um pull ao qual se pede para fixar recusa uma entidade assim antes que qualquer coisa seja resolvida; Uma entidade por diretório expõe a regra. Um pull que não fixa não grava nada ao lado de uma entidade e não julga seu diretório.
aggrega build confronta seus arquivos com ele. Um build lê o lock e faz três comparações:
- O digest de cada arquivo importado é calculado novamente e comparado com sua linha, um arquivo
boundary.artifactsexatamente como um arquivoartifacts. Um arquivo editado depois de ser fixado interrompe o build com[CATALOG_ERROR E0026], nomeando o artefato como sua linha o nomeia, o arquivo importado e ambos os digests. - O digest dos arquivos de uma origem local é calculado novamente e comparado com suas linhas, como um único conjunto, antes que o provider leia a origem. Um arquivo editado, adicionado ou removido desde o pin interrompe o build com
E0305sob a instância de componente cuja origem ele é, nomeando cada um desses arquivos e ambos os digests; um arquivo ao lado da entidade com o qual a origem não contribui não é comparado. Um lock que não registra nenhuma linha para uma origem local não deixa nada a comparar, como descreve A local source no longer matches the pins recorded beside its Recipe (Uma origem local não corresponde mais aos pins registrados ao lado de sua Recipe). - Cada linha de origem é comparada com o digest que o lockfile da Release registra para a mesma origem. Uma divergência interrompe o build com
[FETCH_ERROR E0135], nomeando o lock e ambos os digests. Os dois arquivos são gravados por duas resoluções da mesma origem — a da etapa de pin e a do pull — então divergem quando essas resoluções obtiveram bytes diferentes, ou quando um dos dois arquivos foi editado. Bytes diferentes sob uma mesma versão é a aparência de um upstream que republicou uma versão.
Um lockfile gravado antes da mudança causa a interrupção primeiro, e um pull nomeia o arquivo. O lockfile registra a entidade pelo que ela contém, e o lock e todo arquivo que essas comparações leem fazem parte disso, então um build — ou aggrega pull --verify — que usa um lockfile gravado antes que um arquivo importado, um arquivo de uma origem local ou o próprio lock mudasse é interrompido antes que qualquer uma das três comparações seja executada: The lockfile no longer matches what the release resolves to (O lockfile não corresponde mais ao que a release resolve), nomeando a entidade e ambos os digests. Um simples aggrega pull então nomeia o arquivo, porque confronta o lock com o que a etapa de pin registraria e recusa a entrada cujo pin não corresponde mais: An entity reads an input the lock beside it records no pin for (Uma entidade lê uma entrada para a qual o lock ao lado dela não registra nenhum pin).
Onde o lockfile não tem registro do conteúdo próprio da entidade, são as três comparações que um build encontra. Uma Recipe ou FeatureRecipe que o Manifest nomeia por uma referência que também é o nome de um Component ou de uma Feature que a Release alcança não tem entrada própria: a entrada do lockfile para essa referência registra o Component ou a Feature, então nada muda no lockfile quando os arquivos da Recipe mudam, e um build e um pull de verificação relatam o arquivo alterado com o código acima. A comparação das linhas de origem também é o que um build encontra quando a entrada source_artifacts do lockfile é o registro que mudou enquanto o lock ao lado da entidade não mudou.
Respondendo à interrupção. Se você alterou o arquivo importado de propósito, execute aggrega pin na entidade: a etapa registra o novo digest do arquivo, e o build seguinte o aceita. Se não, restaure o arquivo. Uma origem local que mudou admite as mesmas duas respostas: fixe a entidade novamente ou restaure os arquivos que a interrupção nomeia. Para uma linha de origem que diverge do lockfile, restaure entity.lock a partir do controle de versão, ou execute aggrega pin na entidade para reescrevê-lo.
aggrega pull --verify também o verifica. Um pull de verificação faz as mesmas três comparações sobre os locks ao lado das Recipes e FeatureRecipes que a Release alcança nos seus diretórios de catálogo, relata cada pin que um build recusaria com o mesmo código e nas mesmas palavras, sai com código diferente de zero se houver algum, e não grava nenhum lock.
Onde nenhum lock é comparado. Uma Recipe ou FeatureRecipe resolvida a partir de um registry em vez de um dos seus diretórios de catálogo não tem lock que um build leia; suas origens são confrontadas apenas com o lockfile da Release. E uma origem escrita em um ref: git é registrada no lock no commit para o qual esse ref foi resolvido, enquanto um build procura o pin da origem na versão que a entidade nomeia, então essa linha nunca é comparada — nem por um build nem por um pull de verificação. O lockfile ainda fixa o commit, e todo build verifica o arquivo compactado em cache em relação a ele.
O registro de confiança de plugins
Alguns plugins que o workspace vincula nunca moldam a saída renderizada. Uma vinculação plugins.governance em um papel ir-verdict ou render-verdict, e toda vinculação plugins.linter, retornam um veredito de aceitação ou rejeição e nada mais — nenhum byte deles chega a um artefato. Portanto, eles não fazem parte do que um build reproduz byte a byte, e o lockfile, que fixa exatamente isso, é o lugar errado para eles.
Suas identidades vão, em vez disso, para um segundo arquivo commitado: plugins-trust.yaml, ao lado do lockfile. Ele traz uma entrada por plugin desse tipo, registrando a coordenada de identidade do plugin, a versão selecionada para ele e o digest de conteúdo do artefato resolvido — além da assinatura que o pull verificou para esse artefato, quando verificou uma, e, quando quem publicou depreciou esse artefato depois de publicá-lo, o marcador que o pull encontrou e verificou. O schema do registro de confiança de plugins descreve o arquivo campo a campo.
Faça commit de plugins-trust.yaml junto com o lockfile, pelo mesmo motivo pelo qual você faz commit do lockfile: um registro mantido fora do controle de versão é um registro que ninguém pode revisar e com o qual nada pode ser comparado. Commitado, ele é uma única declaração compartilhada de para qual plugin cada uma dessas vinculações foi resolvida, e um diff sobre ele nomeia a identidade que mudou.
O arquivo só aparece quando há algo a registrar. Um workspace que não vincula nenhum plugin que retorna veredito não resolve nenhuma identidade desse tipo, então o pull não grava nenhum arquivo e não diz nada a respeito — uma ausência, não um arquivo faltando. Quando o pull o cria, ele nomeia o arquivo criado e pede que você faça commit dele. Um pull posterior adiciona uma identidade que o registro ainda não contém e deixa cada identidade já registrada exatamente como está.
Toda mudança neste arquivo é anunciada, e nada mais é. Um pull que altera o registro imprime uma linha por entrada alterada, nomeando o plugin e qual foi a mudança: uma identidade registrada pela primeira vez, uma identidade adotada no lugar da existente (nomeando ambas, para que você veja o que foi trocado), uma depreciação registrada para o artefato que uma entrada já nomeia, uma depreciação removida de uma entrada, uma assinatura registrada em uma entrada ou removida dela, ou a entrada descartada. A linha de criação acima é separada e trata do arquivo, e não de uma entrada, então uma primeira resolução diz as duas coisas: este arquivo é novo e precisa ser commitado, e estas são as identidades que ele contém agora.
Um pull que deixa o registro exatamente como estava não diz nada a respeito. Assim, uma linha sobre este arquivo significa que o arquivo commitado mudou e que vale a pena ler seu diff — o que importa mais aqui do que no lockfile. Tudo o que o lockfile fixa também faz parte do que um build reproduz byte a byte, então uma mudança ali tem um segundo lugar onde aparecer; a identidade de um plugin de veredito não tem nenhum. Este arquivo é o único lugar onde uma barreira trocada fica registrada.
aggrega pull --dry-run não anuncia nada disso, porque não altera nada. Em vez disso, ele lista o registro entre os arquivos que gravaria, como descreve Pré-visualizar o que um pull gravaria.
Uma depreciação é adicionada a uma entrada que o registro já contém, e isso não é o mesmo que reescrevê-la. Se quem publica deprecia um plugin em que você já confia, o próximo aggrega pull registra o marcador na entrada existente desse plugin — a coordenada, a versão e o digest permanecem intactos, porque o artefato não mudou e nada de novo está sendo adotado. Assim, um simples pull pode adicionar um bloco deprecation, e só um upgrade explícito chega a mudar uma identidade. Um marcador só é registrado para o artefato que a entrada já nomeia, e nenhum pull persegue um que deixou de ser publicado: um marcador registrado só sai junto com a entrada que o continha, ou seja, quando essa entrada é descartada ou quando um upgrade explícito resolve o plugin novamente e não encontra nenhum marcador nos bytes que a entrada já registra.
A assinatura verificada é registrada em uma entrada da mesma forma, e todo pull a responde de novo. O pull verifica a assinatura de cada um desses plugins em relação à política de confiança do seu registry a cada execução — um plugin servido por um registry é obtido pela sua versão a cada vez, já que nada o fixa — e registra o que verificou na entrada do plugin, novamente sem tocar na identidade: o modo, o signatário correspondente e o digest do bundle de assinatura que armazenou em cache, a mesma signature que uma entrada do lockfile traz. Ao contrário de um marcador, a resposta substitui o que a entrada continha, e onde o pull não verificou nenhuma assinatura — o plugin não traz nenhuma e nenhuma é exigida, ou skip_signature_verification ou um registry advisory o admitiu — a entrada não registra nenhuma. O bundle de assinatura verificado também é armazenado em cache novamente, e uma cópia em cache que não corresponde mais ao seu digest é reescrita. Assim, uma entrada que perdeu sua assinatura, uma entrada com uma assinatura copiada da de outro plugin, uma entrada cujo bundle de assinatura em cache foi removido ou alterado, ou um registro excluído ou gravado antes de uma assinatura ser registrada, é reparado pelo próximo aggrega pull simples. Um build confronta cada um desses plugins com esse fato: consulte O registro de confiança de plugins na página do build.
Uma identidade resolvida que diverge da registrada interrompe o pull. Uma entrada registrada nomeia tanto uma versão quanto um digest, então a mudança de qualquer um deles é o mesmo evento: o plugin que seria executado não é o plugin para o qual o registro foi revisado. O diagnóstico nomeia o plugin, o que o registro contém e o que esta resolução relatou, nos dois eixos ao mesmo tempo — e o pull para sem tocar no registro, de modo que a identidade revisada continua lá para comparação. Ele é interrompido só pela versão (uma republicação cujos bytes não mudaram) exatamente como é interrompido só pelo digest (um novo push na mesma versão).
aggrega pull --verify faz a mesma comparação. Ele não grava nenhum dos arquivos que um pull commita, então não adota nada; ele relata se esses arquivos ainda descrevem o que um pull resolveria hoje, e o registro é um deles. Ele também confronta a assinatura de cada entrada com a que a própria verificação do plugin feita pelo pull fornece, e relata uma entrada cuja assinatura um pull registraria, substituiria ou removeria — e um plugin para o qual o registro não contém nenhuma entrada quando um build o recusa por não registrar nenhuma assinatura — como descreve Ele compara as assinaturas registradas, nos dois arquivos.
Para adotar uma nova identidade, peça por ela pelo nome: aggrega pull --upgrade --release <release> <plugin>, nomeando o plugin como a vinculação no seu .aggrega-config.yaml o nomeia, sem nenhum sufixo de versão. Isso resolve novamente apenas esse plugin e reescreve sua entrada, deixando intactas todas as outras dependências fixadas e todas as outras identidades registradas — e funciona mesmo que o plugin não tenha pin no lockfile, porque um alvo nomeado também pode nomear uma dessas vinculações. Um aggrega pull --upgrade sem alvos, que resolve novamente todas as dependências, também resolve novamente e reescreve todas as identidades registradas. O mesmo faz aggrega build --upgrade, que executa um pull de atualização completa sem alvos e não tem como nomear um único alvo.
Para remover uma identidade, peça isso pelo nome também. Desvincular um plugin de .aggrega-config.yaml não limpa sua entrada, e isso é proposital: um simples aggrega pull nunca remove uma. Execute aggrega pull --upgrade --release <release> <plugin>, nomeando o plugin como o registro o nomeia — sua coordenada de identidade, que é a string que a interrupção abaixo imprime — e a entrada é descartada, deixando intactas todas as outras dependências fixadas e todas as outras identidades registradas. Um aggrega pull --upgrade sem alvos descarta toda entrada que nenhuma vinculação de veredito nomeia mais, na mesma passagem que resolve novamente todo o resto.
Descartar a última entrada deixa o arquivo no lugar e vazio, em vez de excluí-lo. Um registro vazio não contém nada, então não fixa nada e não interrompe nada — o mesmo que não ter registro algum — e manter o arquivo faz com que a remoção apareça no seu diff como uma remoção.
Um registro que não satisfaz seu schema interrompe todo comando que o lê — um build, um lint com escopo de release e um pull, incluindo um pull que não tem nada próprio a registrar. Um registro esvaziado e um danificado são deliberadamente diferentes: esvaziar é a forma de remover a última entrada, e um registro esvaziado permanece em silêncio, enquanto um arquivo cujo conteúdo não pode mais ser analisado é uma falha, e não um registro vazio — lê-lo como vazio faria do truncamento do arquivo uma forma de desligar a comparação. Restaure-o a partir do controle de versão para recuperar as identidades revisadas.
Um plugin servido a partir da cópia embutida no binário do compilador não é registrado. O pull registra o que adquiriu — obtido de um registry ou lido do cache — e nada é adquirido do binário: esses bytes são identificados pela versão do compilador que os traz, então não há uma resolução própria a registrar. Vincular um plugin que o binário já traz, portanto, não produz nenhuma entrada para ele. Isso é o registro se limitando a artefatos adquiridos, e não uma resolução que falhou.
Um build, um lint com escopo de release e uma validação com escopo de release confrontam a configuração do workspace com o registro. Antes que qualquer uma dessas vinculações seja executada, aggrega build, aggrega lint --release e aggrega validate --release — e as mesmas operações acessadas por meio de aggrega serve e aggrega mcp — comparam as vinculações de veredito que a configuração nomeia com as entradas que o registro contém. Um plugin cujo digest de artefato resolvido não é o registrado é recusado em vez de executado. Uma entrada do registro que nenhuma vinculação de veredito configurada justifica interrompe a execução: uma barreira que foi revisada e agora está ausente deixa uma saída indistinguível de uma saída que essa barreira aprovou, que é exatamente o que quem lê a saída não consegue ver. A interrupção nomeia o plugin e oferece os dois remédios que diferem conforme o que você pretendia — vincule o plugin novamente se a remoção foi um engano, ou execute o upgrade explícito acima se ela foi intencional — e imprime esse upgrade pronto para ser executado. A direção inversa — uma vinculação que o registro ainda não contém — é a primeira ocorrência descrita acima, e nenhuma das duas comparações é interrompida por ela; o requisito de assinatura é a única exigência da qual uma vinculação sem entrada não escapa. As mesmas três superfícies confrontam cada plugin que leem do cache com a assinatura que sua entrada registra, ao carregá-lo, como a página do build descreve para um build. Os escopos de lint do catálogo inteiro e de uma única entidade não consultam nenhum registro.
Uma validação é confrontada com o registro porque executa as mesmas verificações que um build. aggrega validate --release alcança todas as verificações que aggrega build alcança, exceto a gravação dos artefatos, incluindo os plugins de barreira — é isso que faz “isto valida” significar o mesmo que “isto compila” — então a identidade do plugin que ela executa é comparada com o registro exatamente como a de um build. Os outros escopos de aggrega validate não são confrontados com ele: validar o catálogo inteiro, uma única entidade ou um binário de plugin não lê de forma alguma as vinculações de plugins do workspace, então nenhum plugin de veredito é executado neles e não há nada a que um registro possa sujeitá-los.
Confrontar uma configuração com o registro estabelece presença e identidade, e nada além disso. Estabelece que cada barreira que o registro nomeia ainda está vinculada e que cada uma é executada a partir do artefato registrado para ela. Não estabelece que uma barreira executada de fato retornou um veredito, e um caso disso não é detectado em lugar nenhum: uma vinculação cuja function nomeia uma exportação que o plugin de fato declara, que não é a exportação de veredito que seu socket lê, e cuja saída não traz nenhum campo de nível superior fora da forma que esse socket espera — o objeto vazio sendo o caso mais simples — é executada, não retorna nada com base no qual rejeitar e deixa o build passar. Sua saída é indistinguível da de uma barreira que aprova, e nenhuma comparação com o registro consegue notar isso, porque não há nada de errado no registro: o plugin executado é exatamente o registrado, e simplesmente não executou nada. Dois casos vizinhos são interrompidos, então o limite não é mais amplo do que parece — uma function que nomeia uma exportação que o plugin não declara é recusada quando o plugin é carregado, e uma saída que traz um campo de nível superior que a forma do socket não declara é recusada em vez de lida como uma lista de vereditos que por acaso está vazia. Portanto, uma identidade registrada não é, por si só, suficiente para que uma barreira tenha julgado algo.
O digest registrado rege os plugins que o workspace resolve a partir do cache que aggrega pull preenche, e nada que ele resolva de outra forma. Essa é a resolução que uma vinculação de veredito normalmente segue — nada a fixa no lockfile, então seus bytes vêm do cache, e é nessa leitura que o digest resolvido é comparado com o registrado. Um plugin de veredito que o workspace resolve de outra forma nunca chega a essa leitura, e é regido pelo que rege a forma como ele foi resolvido, e não pelo registro: bytes servidos a partir da cópia embutida no binário do compilador são identificados pela versão do compilador que os traz, um .wasm ao lado de sua entidade de catálogo é um arquivo no seu próprio diretório de catálogo, um caminho explícito do sistema de arquivos é o caminho que você nomeou, e um plugin com um pin no lockfile é regido por esse pin. A outra metade de confrontar uma configuração com o registro não é limitada dessa forma: toda entrada que o registro contém ainda precisa ser justificada por uma vinculação configurada, qualquer que seja a forma como esse plugin é resolvido. Assim, o registro estabelece que as barreiras que ele nomeia ainda estão vinculadas, seja lá o que as sirva, e estabelece a identidade de artefato das que são servidas a partir do cache.
Respeitar ou atualizar
Por padrão, aggrega pull respeita um lockfile existente: uma dependência já fixada é resolvida exatamente para sua versão fixada (verificada em relação ao seu digest fixado), apenas as referências ainda não fixadas são resolvidas e adicionadas, e os pins de referências que a Release não alcança mais são removidos. Assim, um novo pull de uma Release inalterada não faz nada — ele reproduz o mesmo lockfile byte a byte (incluindo generated_at). Adicionar uma nova dependência, ou fazer pull depois que uma edição manual removeu um pin, resolve apenas essa lacuna e deixa todos os outros pins intactos.
Uma dependência que um novo pull lê do cache é registrada exatamente como o pull que a baixou a registrou. Sua linha mantém a versão, o digest do conteúdo e o manifest_digest — este último obtido do manifest armazenado ao lado do conteúdo no cache —, junto com a signature e a deprecation que aquele pull verificou no registry. Nada disso é consultado novamente enquanto um build aceitaria a linha, e --detail relata essa dependência como cache-reuse; assim, um novo pull cujas dependências estão todas em cache, sobre um lockfile que registra todas as assinaturas que a configuração de confiança exige e apenas assinaturas que um build aceita, grava o mesmo lockfile quer o registry possa ser alcançado, quer não.
Um novo pull consulta uma assinatura novamente exatamente onde um build recusaria a linha, e há duas linhas desse tipo.
- Uma assinatura exigida que o lockfile não registra. Quando a configuração de confiança exige uma assinatura para uma dependência que o cache fornece e a linha do lockfile não registra nenhuma — a linha foi editada, o lockfile foi gravado do zero sobre um cache que um pull anterior preencheu, ou o requisito foi adicionado depois do pull que gravou a linha —, o novo pull pede a assinatura ao registry dessa dependência, pelo digest do manifest armazenado ao lado dela no cache, exatamente como faz para uma dependência que baixa, e registra a assinatura verificada na linha. Essa linha é a que um build recusa (No verified signature is recorded for an artifact that requires one (Nenhuma assinatura verificada está registrada para um artefato que exige uma)), então fazer pull novamente é o que elimina essa recusa. Um registry que não anexa nenhuma assinatura, ou uma assinatura que a configuração de confiança não aceita, interrompe o novo pull como interrompe um pull que baixou a dependência. As configurações que permitem a um pull admitir uma dependência sem assinatura deixam essa linha como está e não perguntam nada sobre ela:
skip_signature_verificationno nível superior, a mesma chave na entrada do próprio registry, exceto para um tipo que a política de assinatura de todo o workspace exige, e um registry marcado comoadvisory. - Uma assinatura registrada que um build não aceita. Quando a linha registra uma assinatura cujo pacote de assinatura em cache foi removido ou alterado depois do pull que o colocou em cache — ou uma
signaturecopiada de outra linha, cujo pacote está intacto, mas foi criado para outro artefato —, um build recusa a linha, não importa o que diga o requisito de assinatura (A cached signature bundle does not match the digest recorded for it (Um pacote de assinatura em cache não corresponde ao digest registrado para ele), A recorded signature was made for a different artifact (Uma assinatura registrada foi criada para um artefato diferente)). Por isso, o novo pull pergunta novamente ao registry dessa dependência sobre sua assinatura, não importa o que diga o requisito, por meio da mesma verificação pela qual passa uma dependência que ele baixa: o que essa verificação confirma substitui a assinatura da linha, e o pacote que ela indica é colocado em cache novamente, com uma cópia em cache que não corresponde mais ao seu digest sendo regravada — assim, a linha e o cache contêm o que o pull que baixou a dependência deixou. Uma assinatura que a configuração de confiança não aceita interrompe o novo pull como interrompe um pull que baixou a dependência, e o mesmo faz um registry que não anexa nenhuma onde uma assinatura é exigida. Quando a verificação não registra nenhuma —skip_signature_verificationonde se aplica, que não pergunta nada, um registry que não anexa nenhuma assinatura onde nenhuma é exigida, ou um registryadvisoryonde nada é verificado —, a assinatura da linha é apagada, o que um build admite com as mesmas configurações.
Uma linha cuja assinatura registrada um build aceita não é consultada novamente, nem uma linha que não registra nenhuma e para a qual nada exige uma assinatura.
Uma dependência nomeada sem registry, em um workspace que agora não nomeia nenhum default_registry, não pode ser consultada. Sua linha foi vinculada a um registry pelo pull que registrou sua assinatura, e sem um padrão não há registry a quem perguntar. Quando essa linha registra uma assinatura que um build não aceita, o novo pull é interrompido com a própria recusa do build, informando que nenhum registry está configurado para consultar a linha novamente, e deixa o lockfile como estava. Configurar como default_registry o registry de onde veio a dependência e fazer pull novamente corrige isso.
O que esse respeito governa é o que um registry ou o cache fornece. Uma entidade que um diretório de catálogo local fornece é resolvida a partir desse diretório, na versão que seu arquivo declara, e a entrada que o lockfile registra para ela não é consultada no caminho. O lockfile ainda registra essa entidade, então você a verá lá — mas editar essa entrada manualmente não mantém a entidade na versão que você escreveu, e a próxima reconciliação regrava a entrada para corresponder ao arquivo. Para mudar qual versão de uma entidade fornecida localmente uma Release resolve, edite o arquivo do catálogo em vez do lockfile.
Um pin nomeia bytes, não um lugar, então uma entrada de cache que não contém mais seu pin é ignorada em vez de considerada confiável. Uma entidade editada no lugar — um novo corpo sob a mesma version — deixa no cache de conteúdo o corpo anterior sob esse nome e essa versão. Um diretório de catálogo é lido primeiro, então uma entidade que algum deles ainda fornece é fixada a partir de seu arquivo, e a entrada obsoleta nunca é lida. A renderização que o pull executa para descobrir as entradas externas da Release lê cada pin como um build faz, a partir do diretório de catálogo que contém os bytes fixados, e relata a entrada ignorada com o aviso que aggrega build imprime. Quando nenhum diretório de catálogo fornece a entidade e um registry pode ser alcançado, o pull baixa novamente a versão fixada, regrava a entrada e informa isso na saída de erro padrão, nomeando a entrada e os dois digests:
reuse: cache entry for <name>:<version> held <digest the entry held>, not the pinned <pinned digest>; refreshed from the registry (pin unchanged)Os bytes baixados são confrontados com o pin como em qualquer download sob um pin, então um registry que fornece outros bytes sob essa versão interrompe o pull, como descrito abaixo. Quando nenhuma origem contém os bytes fixados — nenhum diretório de catálogo fornece a entidade, a entrada de cache contém outros bytes, e nenhum registry fornece a versão fixada ou a execução não alcança nenhum —, o pull e aggrega pull --verify são interrompidos com E0135 — ou E0133 quando o manifest da entrada de cache não é o que o lockfile fixa —, nomeando cada origem que leram e o que ela continha; quando a execução não alcançou nenhum registry, a interrupção também nomeia a etapa que baixa novamente a versão fixada.
Para atualizar versões fixadas, execute aggrega pull --upgrade --release <release> — ele descarta os pins existentes e resolve novamente todas as dependências para as versões mais recentes que as satisfazem. Atualizar é o ato explícito; o padrão nunca deixa uma dependência fixada flutuar. Isso espelha a convenção de npm ci / cargo / go build (o padrão materializa o lock; atualizar é opcional), e é o que torna seguro o pull automático de aggrega build — o build resolve exatamente o que o lockfile fixa, nunca movendo uma versão silenciosamente.
Essa forma sem alvos descarta todos os pins registrados, então pede confirmação antes de fazer qualquer coisa. Responda a ela antecipadamente com --yes para uso não interativo; se a entrada padrão não for um terminal e não houver --yes, ela recusa em vez de esperar uma resposta que ninguém pode dar. Nomear alvos (aggrega pull --upgrade --release <release> <uri>) mantém todos os pins que não foram nomeados, então essa forma não pergunta nada. aggrega build --upgrade executa a forma sem alvos e está sujeito às mesmas condições.
Se os bytes de uma versão fixada no registry não corresponderem mais ao digest que o lockfile registrou (uma violação de imutabilidade upstream), pull é interrompido com um erro de integridade em vez de adotar silenciosamente os bytes alterados — execute --upgrade para fixar novamente de forma deliberada.
Verificar um lockfile sem gravá-lo
aggrega pull --verify --release <release> responde a uma pergunta: executar aggrega pull agora mudaria o lockfile, ou o registro de confiança de plugins ao lado dele? Ele realiza a resolução que um pull realizaria, compara o lockfile e o registro com ela e para antes que qualquer coisa que um pull efetiva seja gravada — o lockfile, o registro de confiança de plugins e cada entity.lock ficam como estão. Ele termina com código diferente de zero se o lockfile estiver ausente e em qualquer diferença, nomeando cada uma. Marcadores de descontinuação não são comparados, como descrito abaixo. Ele é recusado junto com --upgrade, com --dry-run e com --pin-sources, seja qual for o valor dado a essa flag: uma verificação nem registra um pin que falta em um entity.lock nem é interrompida por ele, então a flag não mudaria nada.
Ele respeita os pins registrados exatamente como um pull faz. Uma dependência que o lockfile fixa é resolvida para sua versão fixada e verificada em relação ao seu digest fixado, e uma entidade que um diretório de catálogo local fornece é resolvida a partir desse diretório, como descreve Respeitar ou atualizar. Assim:
- Uma referência cujo registry publicou uma versão mais recente desde o pull não é desvio. Um pull manteria seu pin, então o lockfile ainda é o que um pull gravaria;
aggrega pull --upgradeé como a versão mais recente é adotada. - Um registry que agora fornece bytes diferentes sob uma versão fixada interrompe a verificação com o erro de integridade que interrompe um pull, em vez de relatar a mudança como desvio.
- Uma linha do lockfile editada manualmente, uma Release editada e uma entidade editada em um diretório de catálogo local são relatadas, cada uma, porque cada uma é uma diferença entre o lockfile e o que um pull resolve agora.
Ele lê e preenche o cache como um pull faz. Uma entrada que o cache contém sob seu pin — uma entidade de catálogo ou o .wasm de um plugin — é lida dali sem perguntar a um registry, o que permite que uma verificação seja executada no modo offline sobre um workspace que um pull conectado preencheu. Uma entrada que o cache não contém é baixada, como um pull a baixa, e uma que não corresponde mais ao seu pin é tratada exatamente como um pull a trata. Assim, uma verificação pode acrescentar ao cache, e nunca move um pin.
Compara as assinaturas registradas, nos dois arquivos
A assinatura que um pull verificou para um artefato faz parte do que ele grava: a signature em uma entrada do lockfile, e em uma entrada de plugins-trust.yaml para um plugin vinculado a uma função de veredito. Uma vez que os pins concordam, uma verificação confronta cada assinatura registrada com a que um pull registraria agora, e relata cada uma que um pull registraria onde nenhuma está registrada, substituiria ou apagaria, sob A recorded signature is not the one a pull would record (Uma assinatura registrada não é a que um pull registraria). Cada uma dessas entradas, em qualquer um dos arquivos, é nomeada na mesma execução.
Quais entradas do lockfile ela consulta é escolha do próprio pull. Um novo pull pergunta a um registry sobre a assinatura de uma entrada exatamente onde Respeitar ou atualizar descreve, e uma verificação segue essa mesma escolha:
- Duas são relatadas sem perguntar a um registry, porque um pull as regrava não importa o que o registry responda: uma entrada que o cache fornece e que não registra nenhuma assinatura onde a configuração de confiança exige uma — o pull registra a assinatura do artefato, ou para onde nenhuma pode ser estabelecida — e uma entrada cuja assinatura registrada foi criada para outro artefato, que o pull substitui pela do próprio artefato.
- Toda outra entrada que um pull consultaria novamente é perguntada, porque só a resposta do registry diz se o pull a mudaria: uma entrada cujos bytes esta verificação baixou, e uma entrada cujo pacote de assinatura em cache foi removido, está ilegível ou foi alterado. A verificação pergunta ao registry, como o pull faria, e relata a entrada onde a resposta registra, substitui ou apaga sua assinatura. O pacote de assinatura que ela verificou é colocado em cache como um pull o coloca, então uma entrada cujo pacote em cache foi removido, enquanto seu registry ainda fornece a assinatura registrada, passa e deixa o cache reparado.
Uma entrada cuja assinatura registrada um build aceita, e uma entrada que não registra nenhuma e para a qual nada exige uma assinatura, não são consultadas, nem por um pull nem por uma verificação.
O registro de confiança de plugins é confrontado com o mesmo pull. Todo pull verifica em seu registry a assinatura de cada plugin vinculado a uma função de veredito, e o mesmo faz uma verificação, que relata uma entrada cuja assinatura essa verificação registraria, substituiria ou apagaria. Um plugin para o qual o registro não contém nenhuma entrada é relatado onde um build o recusa por não registrar nenhuma assinatura, porque um pull grava uma entrada com sua assinatura e o build recusa o plugin até lá. Qualquer outro é um primeiro avistamento, que uma verificação não relata, assim como não relata nenhuma identidade que o registro ainda não contém. No modo offline, uma verificação não pergunta nada a nenhum registry sobre esses plugins, e Offline descreve o que ela relata em seu lugar.
Marcadores de descontinuação não são comparados. Um marcador anexado a um artefato depois do pull é estado do registry, e ele muda sem que nada no workspace mude; uma verificação que falhasse por causa dele faria falhar uma checagem sobre arquivos que você não tocou. Pelo mesmo motivo, um marcador registrado alerta um build em vez de interrompê-lo. Assim, um pull pode registrar um marcador em uma entrada que uma verificação aprovou.
Prévia do que um pull gravaria
aggrega pull --dry-run --release <release> resolve as dependências exatamente como um pull comum e então, em vez de gravar, imprime o que teria gravado: um cabeçalho nomeando o caminho de cada arquivo, seguido do conteúdo que esse arquivo teria.
aggrega pull --dry-run --release release.yamlEle nomeia todos os arquivos, não apenas o lockfile. O lockfile, o entity.lock ao lado de cada Recipe e FeatureRecipe cujos pins registrados mudariam com --pin-sources, e o registro de confiança de plugins aparecem todos no mesmo relatório, porque uma prévia que mostrasse apenas o lockfile ensinaria a você que o lockfile é tudo o que muda. Um pull que seria interrompido em uma entidade não fixada também é interrompido com --dry-run, pelo mesmo motivo: o que uma prévia mostra é o que o pull faria. Os arquivos que um pull deixaria idênticos byte a byte não aparecem de forma alguma — um nome no relatório significa que esse arquivo está prestes a mudar. A última linha os conta, e um workspace que um pull não mudaria relata uma contagem de zero.
Nada no disco muda. Nenhum lockfile é gravado ou criado, nenhum lock de entidade é gravado ou removido, e nenhum registro de confiança é criado ou alterado. Quando uma capacidade é fornecida por mais de um plugin de provider e nada escolheu entre eles, a execução é interrompida nomeando o que fornecer, em vez de oferecer gravar a escolha na sua configuração — uma prévia não edita um arquivo de configuração de passagem.
A resolução em si ainda é executada, então o cache ainda é preenchido. Quais entradas externas uma Release consome é um produto de sua renderização, e uma execução que se recusasse a resolver não teria nada a relatar, então --dry-run baixa e armazena exatamente como um pull faz. O conteúdo sob .aggrega/cache só é lido pelos pins que um lockfile registra, então preenchê-lo não muda nada do que um build resolve; o que um dry run mostra é o que um pull gravaria.
Um --upgrade sem alvos não pergunta nada com esta flag. A confirmação existe porque uma atualização completa descarta todos os pins registrados, e uma prévia não descarta nenhum — então aggrega pull --dry-run --upgrade --release <release> é a forma a usar quando o que você quer saber é quanto uma atualização lhe custaria, e ela é executada sem uma resposta.
Ela não é aceita com --verify, que já não grava nenhum desses arquivos. O par deixaria a flag sem efeito enquanto daria a impressão de que ela fez algo, então é recusado em vez de ignorado.
Uma coisa que uma prévia com fixação nem sempre consegue mostrar por inteiro, e ela avisa quando isso acontece. Um pull solicitado a fixar regrava o entity.lock ao lado de cada Recipe e FeatureRecipe e então renderiza a Release para descobrir suas entradas externas; uma prévia deixa esses locks como estão, então, onde um pin registrado ali ficou obsoleto — você editou um arquivo importado desde que ele foi fixado, por exemplo —, essa renderização é confrontada com o digest obsoleto que o lock não gravado ainda registra, e para. Todo o resto do relatório é exatamente o que um pull gravaria; apenas os pins de entradas externas do lockfile relatado estão incompletos. A execução informa isso tanto na sua saída quanto nos seus diagnósticos, em vez de entregar a você um lockfile que parece completo. Uma primeira resolução de um workspace não é afetada, porque ainda não há nenhum digest registrado em relação ao qual algo possa estar obsoleto.
A composição que esses pins descrevem
Um lockfile fixa o que um build desta Release consumirá, então a resolução traça a composição que esse build traça: ela resolve os documentos, aplica as transformações que as vinculações do workspace declaram e submete o resultado às verificações que um build faz sobre um grafo concluído. Duas coisas decorrem disso, e ambas aparecem na passagem que grava o lockfile, e não no primeiro build que o lê.
Uma composição que essas verificações rejeitam interrompe o pull. Uma aresta uses: cujo destino não satisfaz o selector: de seu socket, uma Feature vinculada a um componente que seu appliesTo: não admite, e qualquer outra violação que essas verificações relatem param este comando, com o diagnóstico que um build dos mesmos documentos imprime — e a interrupção nomeia todas as constatações em uma única execução, em vez de apenas a primeira, de modo que uma passagem entrega a você a lista inteira a corrigir. Isso acontece antes da gravação, então <release-stem>.lock e plugins-trust.yaml ficam exatamente como estavam, e uma Release que não compila nunca é registrada como uma que foi resolvida corretamente. O que isso não cobre são as vinculações que retornam um veredito: nenhuma vinculação ir-verdict ou render-verdict é executada aqui, então um veredito de rejeição para o build, o lint com escopo de release ou a validação com escopo de release que o despacha, e não este comando.
Uma vinculação em uma função que molda o grafo é executada durante essa passagem, então um plugin que não é resolvido interrompe o pull. Uma vinculação label-transform decide os rótulos dos nós antes que qualquer coisa seja comparada com eles, e uma vinculação annotation-transform injeta anotações que se expandem em vinculações de Feature — ambas mudam o que o grafo contém, então traçar o grafo significa despachá-las, e despachá-las significa ter os bytes próprios de cada plugin. Um plugin cujos bytes essa passagem não consegue obter interrompe a execução, nomeando o plugin e o que não pôde ser encontrado para ele — a mesma recusa que um build do mesmo workspace faz quando não consegue obtê-los. O que ela despacha é a lista de vinculações que essa passagem acabou de resolver, com as configurações e os arquivos de definição que o lockfile registra para que um build posterior os reconstrua, de modo que ambas as passagens executam a mesma vinculação sobre a mesma entrada.
Um Plugin que uma etapa de pipeline nomeia e que nada contém também interrompe o pull. Cada Plugin que a pipeline de uma Recipe ou FeatureRecipe nomeia é resolvido com as outras dependências da Release — a partir de um diretório de catálogo, da cópia dentro do binário do compilador, do cache de conteúdo ou do registry —, e um que nenhum deles contém é um que um build também não conseguiria carregar. Então o pull para antes de gravar qualquer coisa, nomeando o Plugin e a Recipe ou FeatureRecipe cujo pipeline o nomeia, com a condição que um build levanta quando chega a essa etapa (A plugin reference is not a Plugin entity (Uma referência a um plugin não é uma entidade Plugin)). Isso vale para toda Recipe e FeatureRecipe que o Manifest vincula, incluindo uma que nada nesta Release vincula, porque cada uma é resolvida e fixada, seja renderizada ou não. Publique o Plugin, ou coloque-o em um diretório de catálogo com seu .wasm compilado ao lado, e faça pull novamente.
Essa interrupção e uma execução degradada são resultados diferentes, deliberadamente. Uma renderização que não consegue terminar — a que tanto Como a resolução encontra entradas externas quanto Offline descrevem — deixa todos os pins de dependências corretos, então os pins são gravados e a falta é relatada. Uma composição que as verificações rejeitam não é uma falta no que foi resolvido: é uma Release que não compila, então nada é fixado para ela e a execução para.
O cache
O conteúdo baixado é armazenado sob .aggrega/cache, dividido em uma subárvore entities/ para entidades de catálogo, uma subárvore source-artifacts/ para artefatos de origem e uma subárvore inputs/ para as entradas externas que uma renderização consome. O slot de uma entidade de catálogo é nomeado por seu tipo, sua coordenada e sua versão — de modo que um Component e uma Recipe que compartilham uma coordenada e uma versão mantêm dois slots —, o de um artefato de origem pelo local de onde foi baixado, sua versão e um prefixo do digest de seu conteúdo, e o de uma entrada externa pelo digest de seu conteúdo; o que um build lê de qualquer um deles é verificado em relação ao que o lockfile registra. Pins de versão idênticos, portanto, compartilham um slot entre Releases. Cada slot de artefato de origem contém o arquivo compactado de referência, uma extração regenerada e um pequeno arquivo de metadados; a extração é regenerada a cada leitura, então a saída do build depende do arquivo compactado e do lockfile, não do estado dos arquivos extraídos.
Todo nome que o cache deriva de um valor é aceito por Windows, Linux e macOS. Uma coordenada, uma versão, um host de registry ou um digest contém caracteres que um nome de arquivo não pode conter: a / entre as partes de uma coordenada, o : antes de uma versão, dentro de sha256: e antes da porta de um registry. Então cada valor — um tipo, uma coordenada, uma versão, um host de registry ou um digest — é transcrito antes de se tornar um nome de diretório ou de arquivo — uma letra minúscula, um dígito, ., _ e - são escritos como estão, e qualquer outro caractere é escrito como um escape que começa com +. O Component core/devtool/adminer:1.0.0 na versão 1.0.0 é o slot entities/+zx000043omponent/core+zsdevtool+zsadminer+zx00003a1.0.0/1.0.0/, e um slot nomeado por um digest de conteúdo é sha256+zx00003a<hex>. Uma letra maiúscula também é escapada, de modo que duas coordenadas que diferem apenas em maiúsculas e minúsculas mantêm dois slots em um sistema de arquivos que não diferencia maiúsculas; um nome que o Windows reserva para um dispositivo, como con, tem sua primeira letra escapada; e nenhum nome termina em ponto. Dois valores diferentes nunca compartilham um nome, e um valor tem o mesmo nome em todas as máquinas. aggrega cache status lista cada entrada pelos valores a partir dos quais seus nomes foram transcritos — uma entidade de catálogo por sua coordenada, versão e tipo —, em vez de pelos nomes transcritos.
Uma entrada de um arquivo compactado mantém o nome que seu publicador lhe deu, então no Windows uma entrada que o Windows não consegue conter é recusada. Os arquivos que o arquivo compactado de um artefato de origem ou de uma entidade de catálogo contém são dispostos com os nomes que o arquivo compactado lhes dá, não transcritos pelo cache. Quando a extração é executada no Windows, uma entrada que contém uma parte que o Windows não consegue conter como está escrita — um nome que ele reserva para um dispositivo, como NUL ou aux, em qualquer combinação de maiúsculas e minúsculas e com ou sem extensão, ou uma parte que termina em ponto ou espaço — é recusada com E0340, nomeando a entrada, e nada desse arquivo compactado é disposto. No Linux e no macOS, essa entrada é disposta com o nome que tem. Uma entrada que sobe para fora do diretório da extração é recusada em todas as máquinas.
O slot de uma entidade de catálogo só é uma entrada com seu manifest. O slot contém o conteúdo que um registry forneceu e, ao lado, o manifest que descreve esse conteúdo. Um slot que contém apenas o conteúdo — um download que parou entre as duas gravações, ou um arquivo colocado ali manualmente — não é uma entrada: um pull, e um pull de verificação, pedem-no novamente ao registry da entidade onde um pode ser alcançado, enquanto um build, que nunca baixa nada, trata a entidade como ausente, como um pull faz quando nenhum registry pode ser alcançado.
O que chega ao cache é submetido a duas coisas: a forma que o próprio schema da entidade descreve e o lugar que o cache nomeia para ela. Um corpo baixado de um registry passa pelo schema de seu tipo — a mesma verificação que o lê de volta — antes de ser colocado em cache, então uma entidade ou biblioteca publicada que o registry fornece e que seu próprio schema recusa interrompe o pull, nomeando o que foi baixado, em vez de ser colocada em cache e encontrada mais tarde como uma falha. E um valor a partir do qual uma localização de cache é construída e que colocaria um arquivo em cache em um lugar diferente do que o valor nomeia — uma versão que é um caminho em vez de uma versão, um caminho url de origem ou um module_subdir que sobe acima de seu lugar — é recusado onde a localização é construída, nomeando o valor problemático. Um valor escrito em uma Recipe ou FeatureRecipe de sua autoria é submetido da mesma forma no momento em que a localização de cache é construída a partir dele — e o module_subdir de uma origem git antes ainda, antes de o repositório ser baixado, como descrito abaixo.
Um repositório git é arquivado a partir do seu próprio checkout. Para uma origem git-repository, o pull faz checkout do repositório no commit que fixa e arquiva o diretório que module_subdir nomeia, ou o repositório inteiro. Um module_subdir que sobe acima do repositório como está escrito — ../shared ou ..\shared — é recusado antes de o repositório ser baixado, com E0307 citando o valor, então nada ao lado do checkout é lido. Um link simbólico que o repositório versiona é arquivado como o arquivo ou diretório para o qual aponta, quando este fica dentro do repositório — o próprio module_subdir pode ser um link assim. Um que leva para fora do repositório interrompe o pull com E0321, nomeando o link e para onde ele leva, e nada é colocado em cache, de modo que um repositório do qual você faz pull não pode fazer o pull copiar um arquivo da sua máquina para o artefato. O checkout é removido assim que o pull para, então a mensagem nomeia o link pelo seu lugar no repositório, e o repositório e a revisão que a origem nomeia, em vez de um diretório que não existe mais. Cabe ao repositório mudar o link. O limite do workspace enuncia a regra que isso aplica.
O cache é ancorado no workspace, e não no diretório a partir do qual você executou o comando, então um workspace tem um único cache, e um pull executado a partir de um subdiretório preenche o mesmo armazenamento que um build executado a partir da raiz lê.
Um pull em que nenhum workspace foi encontrado e nenhum foi nomeado é recusado antes que qualquer coisa seja baixada. Quando nada nomeia uma raiz e a descoberta não ancora nada — a partir da pasta em que você o executa ou, para uma Release nomeada por um caminho absoluto, a partir da própria pasta dessa Release —, a pasta seria a raiz, e um cache gravado sob ela a tornaria um workspace. Então o pull para, não grava nenhum lockfile nem cache, e nomeia a pasta e as duas maneiras de resolver isso: nomeie seu workspace com --workspace-root ou AGGREGA_WORKSPACE_ROOT, ou dê a essa pasta um .aggrega-config.yaml com um bloco workspace:. A ferramenta de pull de aggrega mcp, chamada sem workspace_root em um servidor iniciado sem raiz, é recusada da mesma forma; Configuração lista os outros comandos para os quais isso vale.
Compilar onde a rede não pode ser alcançada
Como este comando é a única etapa que acessa o exterior, uma única execução conectada basta para tornar locais todos os builds posteriores. Essa execução grava o lockfile e preenche o cache do workspace com os bytes que esses pins nomeiam, e um build então não precisa de nada além deles.
Três coisas vão para a máquina desconectada:
- A Release e seu lockfile. Faça commit de
<release-stem>.lockao lado da Release; é ele que diz ao build para qual versão e digest cada dependência foi resolvida. plugins-trust.yaml, quando o workspace vincula um plugin que retorna veredito. Um build compara as vinculações de veredito que sua configuração nomeia com esse registro antes que qualquer uma delas seja executada, então levar o registro é o que submete o build desconectado às identidades que foram revisadas e às assinaturas que o pull verificou para elas. Faça commit dele ao lado do lockfile, como descreve O registro de confiança de plugins.- O diretório do cache. As entidades, os artefatos de origem e as entradas fixadas ficam todos sob ele, e tudo o que um diretório
catalog_dirslocal não fornece é lido dali.
Compile na máquina desconectada normalmente. Definir o modo offline nela vale a pena mesmo que um build sobre um lockfile completo leia seu fechamento do cache: isso transforma um possível acesso à rede em uma recusa imediata que nomeia o modo, em vez de uma tentativa de conexão que precisa primeiro esgotar o tempo limite. Tudo o que o cache não contém, e toda entrada externa que o lockfile não fixa, interrompe o build nomeando o que falta e a resolução que o fixaria — nada é baixado silenciosamente para preencher a lacuna.
Uma máquina isolada da rede e um workspace offline são afirmações diferentes, e vale a pena manter a diferença. Uma máquina atrás de um isolamento de rede pode conter uma cópia local de um registry, ou um catálogo catalog_dirs com tudo de que precisa, caso em que um pull comum nessa máquina pode ser satisfeito sem acessar o exterior de forma alguma. O modo offline descreve o que um comando pode acessar, não o que a máquina contém; Offline expõe o que ele recusa e o que deixa como está.
Offline
No modo offline — a chave de nível superior offline em um arquivo de configuração, AGGREGA_OFFLINE no ambiente, ou --offline na linha de comando —, aggrega pull recusa o acesso à rede. A recusa acontece antes de qualquer tentativa de conexão, e não como um tempo limite esgotado no meio de um download, então um pull offline não alcança nenhum registry nem nenhuma origem remota. Quando um arquivo com commit ou uma variável exportada definiu o modo e você quer contorná-lo para um comando, --offline=false permite a rede apenas para essa execução.
--upgrade é recusado de imediato nesse modo, e é a única opção aqui a que isso acontece. Uma atualização completa faz cada dependência flutuar para a versão mais alta que um registry oferece no momento, então precisa perguntar a um registry o que ele fornece no momento. Um pull comum não: ele respeita os pins que já registra, resolve apenas o que não tem nenhum e, portanto, pode ser satisfeito com o que a máquina contém. A recusa informa qual dos três lugares definiu o modo e como permitir a rede para uma execução.
A resolução então recorre apenas ao que a máquina já contém: a pilha de busca catalog_dirs e o cache sob .aggrega/cache. Com um catálogo e um cache que satisfazem todas as referências, um pull offline termina normalmente e grava um lockfile comum. O lockfile registra o URI, a versão resolvida e o digest de cada dependência, e nunca qual desses lugares forneceu os bytes — então um pull offline e um pull online que resolvem as mesmas versões gravam o mesmo lockfile.
Uma dependência que um pull offline não consegue satisfazer localmente o interrompe. A entrada nunca é ignorada:
- Uma entidade de catálogo que não é resolvida em lugar nenhum interrompe o pull, nomeando a referência e de onde ela foi referenciada, de modo que tanto a dependência ausente quanto aquilo que a solicitou são nomeados.
- Uma
source:remota interrompe o pull, nomeando a origem e dizendo a você para permitir o acesso à rede ou preencher o cache a partir de um ambiente conectado. - Uma dependência que o cache contém e cuja assinatura exigida o lockfile não registra, ou cuja assinatura registrada um build não aceita, interrompe o pull com a recusa offline, nomeando a dependência: registrar a assinatura significa perguntar ao seu registry, como descreve Respeitar ou atualizar. Permitir a rede para essa única execução a registra. Uma assinatura registrada que um build aceita não é consultada novamente, então ela não interrompe um pull offline.
Uma entrada externa é a única que não interrompe, e em vez disso ela informa. A renderização que as encontra não pode baixar o que ainda não está armazenado, então um pull offline sobre uma Release com uma entrada externa não fixada termina, grava todos os pins de dependências que resolveu e relata três coisas: que a renderização não terminou, o que ele fixou, e que um build desta Release será interrompido nomeando a URL. Os pins de dependências que ele gravou estão corretos — nada neles dependia da renderização —, então eles são mantidos em vez de descartados para que um leitor os reproduza.
Isso é deliberado, não uma lacuna, e não há nenhuma chave para isso. Um pull que descartasse trabalho correto custaria a você a parte que deu certo; um pull que ficasse calado entregaria a você um lockfile que parece completo e não está. Informar isso é o único resultado que deixa você em condições de agir: execute o pull novamente a partir de um ambiente conectado, ou de um cujo cache já contenha o conteúdo, e o mesmo comando o fixa.
Assim, um pull offline é uma recusa em tocar na rede, e não um resultado reduzido para tudo o que um documento nomeia, e para entradas externas é uma resolução concluída que diz a você o que não conseguiu alcançar. Um lockfile que existe é um cuja resolução de dependências foi concluída; se suas entradas externas estão completas é o que a própria saída do pull diz a você, e aquilo a que um build então o submete.
--verify no modo offline cobre menos, e informa isso. Perguntar para onde uma ref de origem registrada aponta hoje significa alcançar seu remoto, o que o modo offline recusa. Então um --verify offline verifica as dependências fixadas e pula esse eixo, e imprime uma linha dizendo isso em vez de relatar uma correspondência que nunca estabeleceu. Uma assinatura registrada que só seu registry pode confirmar — em uma entrada do lockfile cujo pacote de assinatura em cache foi removido ou alterado — é pulada da mesma forma, em uma linha que nomeia cada uma dessas entradas:
verify: offline, so the signature the lockfile records for "<reference>" was not checked at its registry, which alone can say whether a pull would record it again; this verify does not cover itUma assinatura registrada que um pull regravaria não importa o que o registry respondesse ainda é relatada offline, porque nenhuma resposta é necessária para sabê-lo, como descreve Compara as assinaturas registradas, nos dois arquivos.
Um plugin vinculado a uma função de veredito que um registry fornece é onde uma verificação offline e um pull offline se separam. Um plugin assim nunca é fixado no lockfile, então todo pull resolve seu .wasm a partir de seu registry, e um pull offline sobre um workspace que vincula um deles para ali, nomeando o plugin como um cujo .wasm não conseguiu resolver — mesmo quando o cache de conteúdo o contém, e esteja ou não esse registry marcado como advisory ou pulando a verificação de assinaturas. Uma verificação offline, em vez disso, não pergunta nada ao registry sobre o plugin: ela lê o plugin do cache de conteúdo, como um build o lê, e para onde o cache não contém seu .wasm ou contém um que não corresponde mais ao digest que seu manifest publicado nomeia. Ela ainda confronta a identidade do plugin com o registro de confiança de plugins e verifica novamente suas funções de host em relação a esse .wasm, e é interrompida onde qualquer um deles diverge, exatamente como uma verificação conectada faz. Ela relata o plugin onde um pull regrava sua entrada não importa o que o registry responda, que é onde um build recusa o plugin por causa de sua entrada: por não registrar nenhuma assinatura, porque sua entrada não registra nenhuma ou o registro não contém nenhuma entrada para ele, ou porque a assinatura que sua entrada registra foi criada para outro artefato, que o pull substitui pela do próprio plugin. Toda outra entrada — uma cuja assinatura um build aceita, e uma cujo pacote de assinatura em cache foi removido ou alterado — ela nomeia em uma linha dizendo que sua assinatura não foi verificada, e não relata nada sobre essa assinatura:
verify: offline, so the signature of "<plugin>" was not checked at its registry, which alone can say whether a pull would record the same signature on its entry in the plugin trust record; this verify does not cover itAssim, uma verificação offline deixa passar uma entrada cuja assinatura um pull conectado substituiria ou apagaria — uma cujo signatário foi editado manualmente, por exemplo, ou uma à qual seu registry não anexa mais assinatura —, e essa linha é a única coisa que diz isso. Uma verificação em uma máquina isolada da rede continua disponível; o que ela não diz a você é se uma ref mudou desde então, ou se uma assinatura pulada seria registrada novamente. Uma checagem que lê apenas o código de saída cobre esses casos somente quando a verificação é executada conectada.
Integração com aggrega build
- Verificação.
aggrega buildverifica cada dependência resolvida em relação ao lockfile e para em caso de desvio: uma entidade, uma biblioteca ou um plugin cujo conteúdo não corresponde mais ao seu pin, uma referência que a Release agora alcança e que o lockfile não fixa ou uma que ele fixa e que a Release não alcança mais, e um arquivo de Release editado desde o pull. Executeaggrega pull --release <release>, o comando que a parada exibe, para resolver isso: o pull resolve a Release como ela está agora, reescreve os pins que mudaram e mantém todos os outros, de modo que nada flutua sem que você tenha alterado. Quando o que mudou é um arquivo sob a fonte local de uma Recipe, o pull indica primeiroaggrega pinpara essa entidade, como descreve O lock da entidade. Um lockfile que este comando acabou de gravar passa nessa verificação, porque o comando executa a mesma verificação antes de gravá-lo; um build que para por desvio logo após um pull recebeu entradas diferentes das do pull — um diretório--catalogpassado a um e não ao outro, ou uma configuração do workspace editada entre os dois —, então execute os dois sobre as mesmas entradas.aggrega validate --releasee toda seleção deaggrega inspectque resolve uma Release submetem o lockfile à mesma verificação e recusam com a mesma parada, de modo que nenhum dos dois deixa passar um lockfile que um build recusa. - Pull automático. Se o lockfile estiver ausente e
auto_pullfor true,aggrega buildexecuta o pull primeiro automaticamente. Seauto_pullfor false, que é o seu padrão, o build para e pede que você faça o pull. O pull que um build executa seguepin_sources_at_pull, de modo que, sobre uma entidade sem pin, ele para exatamente como um pull. A etapa de pull que um build executa é a mesma que esta página descreve, de modo que um build que preenche um lockfile existente para diante de um ref de fonte movido exatamente comoaggrega pull— consulte Determinismo e integridade. - Offline. No modo offline,
aggrega buildusa apenas o que a máquina já contém e recusa o acesso à rede antes de qualquer tentativa de conexão. Uma referência cujo conteúdo não está no cache para o build em vez de falhar no meio de um download, e um build sem lockfile ao qual não se pede que preencha um para indicando o pull que o preencheria, exatamente como faz online.--auto-pullnão é recusado: o preenchimento que ele solicita é o pull que esta página descreve, de modo que, sobre entidades de catálogo já em cache ou presentes em um catálogo local, ele grava o lockfile sem contatar um registry — uma Recipe cujo chart é obtido de uma fonte remota é resolvida novamente, então offline ela para mesmo onde o cache contém esse chart —, e uma referência que nenhum dos dois contém — ou uma em cache cuja assinatura exigida o lockfile não registra, ou cuja assinatura registrada um build não aceita — o interrompe com a própria recusa do pull, que indica essa referência.--upgradeé recusado, pelo motivo que Offline apresenta. - Pesquisa no catálogo. O pull respeita
catalog_dirsde.aggrega-config.yamlmesmo quando nenhum--catalogé fornecido — e os diretórios próprios de uma Release, quando a configuração lhe atribui alguns emworkspace.releases— e resolve a mesma pilha de pesquisa em que vence a primeira correspondência usada poraggrega build, de modo que as dependências que ele fixa correspondem ao que o build pesquisa. Um diretório listado que não é um diretório — nada existe lá, por exemplo — é recusado pelos dois comandos antes que qualquer coisa seja resolvida ou gravada, nomeando a entrada e o arquivo de configuração e a linha que o listam, como mostra De onde as entidades locais são lidas.
Como a resolução encontra as entradas externas
Nada nesta seção altera a regra acima — continua havendo um único momento em que algo é fixado, e é este comando. O que ela descreve é como o comando chega ao terceiro dos três tipos, o que importa quando você integra a resolução a um pipeline, lê uma execução que se degradou ou raciocina sobre por que este comando chega a renderizar.
Uma entidade de catálogo e um artefato de fonte são nomeados cada um em um documento; uma entrada externa, não. Resolver os dois primeiros é questão de ler o que você escreveu. Uma entrada externa é nomeada por um provider, no meio de uma renderização, e quais URLs ele nomeia decorre dos valores sendo renderizados — uma entrada de valores ausente deixa uma subárvore inteira do schema de um chart sem compilar e cada referência remota nessa subárvore sem solicitar. Nenhuma leitura da Release consegue enumerar o conjunto.
Então o comando faz duas coisas em uma única passagem: resolve e fixa o fechamento que os documentos nomeiam e, em seguida, renderiza esse fechamento para ver quais documentos remotos os providers solicitam. Os artefatos renderizados são descartados e os pins são mantidos. Ambos são internos ao único comando, e nenhum é um segundo momento em que algo poderia ser fixado — há uma única gravação do lockfile, e ela contém todos os pins.
Vale a pena conhecer duas consequências antes de integrar a resolução a um pipeline automatizado como uma etapa barata. Ela custa mais do que uma resolução que apenas lê documentos, porque renderiza. E pode falhar por um motivo pelo qual uma resolução apenas de documentos não poderia: um provider que não consegue renderizar esta Release. Quando isso acontece, os pins das dependências ainda são gravados, porque nada neles dependia da renderização, e o diagnóstico indica a etapa que parou, o que foi fixado e que um build vai parar indicando a URL sem pin. A execução não se perde, e Offline mostra o mesmo resultado alcançado de outra forma.
A renderização também submete o lockfile à comparação que um build aplica, antes que qualquer coisa seja gravada. Ela executa a própria sequência do build, então compara o lockfile que este comando está prestes a gravar com aquilo a que um build da mesma Release resolve, exatamente como um build compara um lockfile que encontra em disco. Um lockfile que essa comparação recusa não é gravado — nem qualquer outra coisa que o comando teria gravado depois —, e o comando para dizendo que a resolução e o build discordam sobre aquilo de que a Release depende, seguido de cada entrada que a comparação indicou. Nada nos seus arquivos pode causar isso, e resolver novamente chegaria à mesma discordância, então relate o problema junto com a Release em vez de tentar de novo. É a única falha de renderização que impede a gravação, e é por isso que um build da mesma Release, sobre as mesmas entradas, não relata desvio sobre um lockfile que este comando gravou.
Não há opção para pular a renderização. Uma opção assim preservaria, como alternativa, exatamente a surpresa que um único momento elimina: uma Release que resolve sem problemas enquanto uma entrada de que sua renderização precisa fica sem pin, descoberta só no momento do build.
--auto-pull incorpora essa mesma resolução a um build, e o build renderiza uma única vez. A renderização do preenchimento é a que encontra e fixa as entradas externas, e o build apresenta essa renderização em vez de executar uma segunda, de modo que um build de um único comando custa a mesma renderização que um build comum sobre um lockfile já preenchido. aggrega build explica quais flags de renderização de um build chegam a ela.
O conjunto decorre dos parâmetros da Release, que é como os pins de componentes já se comportam. Editar os parâmetros de uma Release entre a resolução e o build é uma edição da Release, de modo que o build para na comparação de desvio indicando o arquivo, antes que qualquer renderização possa solicitar uma URL sem pin; a solução é este comando. Parâmetros importados de um arquivo separado não são registrados por conteúdo, então editar esse arquivo em vez disso chega à renderização, que para indicando a URL sem pin — com uma solução que também indica este comando.
Determinismo e integridade
O source: de uma Recipe pode definir sua versão por template a partir dos values e da infra resolvidos da Release (e sobre os locals definidos neles); esses são resolvidos no momento do pull e o resultado é fixado. O pull avalia apenas as entradas locals: que os campos source: leem, e as entradas que essas leem por sua vez, somente com os helpers de template próprios do Aggrega: uma entrada lida pela fonte que chama uma função Sprig para o pull indicando a entrada, o campo e a função, enquanto uma entrada que nenhum campo source: lê fica para o build, que a avalia e verifica quando renderiza a Recipe — consulte Resolving a source: coordinate registers a narrower function set (Resolver uma coordenada source: registra um conjunto de funções mais restrito). Uma tag ou branch Git mutável é fixada no commit concreto para o qual aponta, e o ref que você escreveu é registrado ao lado. No momento do build, o digest do arquivo compactado em cache é verificado novamente em relação ao lockfile, de modo que um cache adulterado é detectado.
Um ref registrado fica preso ao commit que fixou. O ref é registrado porque execuções posteriores o consultam novamente, não por legibilidade — um build pergunta qual artefato ele nomeia, e um pull pergunta se ele ainda aponta para onde apontava. Um pull que não é um upgrade pergunta novamente a cada ref registrado para onde ele aponta, e um ref que se moveu em seu remoto para a execução — indicando o artefato, o ref, o commit que o lockfile fixa e o commit para o qual ele resolve agora — em vez de adotar a mudança. Execute aggrega pull --upgrade --release <release> para adotá-la. Um upgrade direcionado, que nomeia URIs de entidades, não faz isso: uma referência de fonte não é uma entidade que você possa nomear, então uma execução direcionada a mantém exatamente como faz um pull simples.
Essa verificação é a única coisa que a nova verificação do digest no momento do build não pode fazer por você. Um pull que adotasse um ref movido reescreveria os bytes obtidos e o digest registrado no mesmo ato, de modo que os dois valores que um build compara teriam mudado juntos e concordariam — e você estaria fazendo o build de um conteúdo de fonte diferente daquele em relação ao qual o lockfile foi revisado, sem que nada relatasse isso.
Apenas um ref que o lockfile registra fica preso dessa forma, e um ref é registrado sempre que você escreve um. Uma Recipe que nomeia sua fonte apenas por version: não tem ref, então não há nada que uma execução posterior precise consultar novamente — e essa é a resposta certa, porque uma versão que você mesmo escreveu não pode mudar sem que você saiba. A referência do lockfile informa o que é registrado.
Escreva o ref, não o commit. Um build encontra um artefato de fonte git pelo ref que você escreveu, comparado com o ref que o lockfile registrou, de modo que ref: v1.2.3 faz o build sobre o commit em que essa tag foi fixada e o commit nunca precisa aparecer na sua Recipe. Indicar uma tag mutável em version: não funciona e não foi feito para funcionar: version: é comparado como está escrito, e para uma fonte git o lockfile fixa um commit.
O lockfile fixa o conteúdo obtido de registries e fontes remotas, e registra o digest de cada entidade que resolve a partir dos seus diretórios de catálogo — sobre o arquivo da entidade e cada arquivo que ela nomeia ao lado, como descreve O lockfile — e de cada arquivo de Release que a resolução leu. Os arquivos de uma fonte que começa com ./ ou ../, e um arquivo de artefato que uma entidade importa, também são fixados um a um no lock ao lado dessa entidade, como descreve O lock da entidade, e é isso que indica o que mudou; a integridade do restante do seu workspace entre builds é responsabilidade do sistema de controle de versão. Consulte saída idêntica byte a byte para o escopo da garantia de determinismo.
Autenticação
As credenciais de registry são lidas apenas da configuração de credenciais do Docker: config.json no diretório que DOCKER_CONFIG indica, ou ~/.docker/config.json quando essa variável não está definida, junto com qualquer credential helper ou chaveiro do sistema operacional ao qual o arquivo delega por meio de credsStore ou credHelpers. aggrega login <registry> grava uma credencial ali, assim como docker login <registry>; execute qualquer um dos dois antes de aggrega pull para um catálogo OCI ou um registry de charts privado. Os arquivos que podman login e helm registry login gravam não são lidos.
Uma configuração de credenciais que não pode ser lida é informada sem o que ela contém. Quando config.json não é um JSON válido, o valor auth de uma entrada não é um usuário e uma senha unidos por dois-pontos e codificados em base64, ou um credential helper que o arquivo nomeia não consegue responder, o acesso ao registry falha com uma mensagem que nomeia o registry e o arquivo de credenciais, nunca o que o arquivo ou a entrada contém. aggrega login e aggrega logout informam da mesma forma um config.json que não é um JSON válido, e não alteram nada nele. Corrija o arquivo; uma entrada que não pode ser lida também pode ser substituída com aggrega login <registry>.
Um repositório de charts do Helm clássico ou um arquivo de chart (helm-https-chart), um fragmento de compose (compose-https-fragment) e um repositório Git acessado por HTTP ou HTTPS (git-repository) se autenticam com o arquivo netrc, o arquivo de credenciais por usuário que curl e Git também leem. É o único armazenamento de credenciais que esses três tipos leem: ~/.config/helm/repositories.yaml e os credential helpers do Git não são lidos. Um repositório Git acessado por SSH se autentica pelo agente SSH e não lê nenhum arquivo netrc.
machine charts.example.com login deploy-bot password <token>Qual arquivo é lido. O arquivo que a variável de ambiente NETRC indica, quando ela está definida. Caso contrário, .netrc no seu diretório pessoal; no Windows, _netrc em %USERPROFILE% quando esse arquivo existe, e .netrc ali quando não existe. Um arquivo ausente não contém credenciais e não é um erro. Um arquivo que existe e não pode ser lido, ou que não segue o formato netrc, interrompe o comando com E0360, nomeando o arquivo — e, para uma falha de formato, a linha —, mas nunca o que o arquivo contém: The netrc file cannot be read (O arquivo netrc não pode ser lido). No Linux e no macOS, um arquivo netrc que outros usuários da máquina podem ler gera um aviso que o nomeia; torne-o legível apenas por você (chmod 600).
Qual entrada responde a uma solicitação. Cada solicitação é buscada pelo seu host — o nome do host sem a porta, sem diferenciar maiúsculas de minúsculas — e é respondida pela primeira entrada machine que nomeia esse host, ou pela entrada default quando nenhuma o nomeia. O login e a password da entrada são enviados como credenciais HTTP basic, tanto por http quanto por https; uma entrada à qual falte um deles não envia nada. Um repositório cujo índice coloca seus charts em outro host é respondido solicitação por solicitação: a solicitação do índice usa a entrada do host do repositório, e a solicitação do chart, a do host do chart. Uma solicitação feita sem credencial precisa poder ser lida anonimamente, e um servidor que responde 401 ou 403 interrompe o pull como uma busca não autorizada, cuja correção nomeia a entrada a adicionar e o arquivo em que ela foi procurada.
A credencial não é gravada em lugar nenhum. Ela é lida quando uma busca é executada e enviada com a solicitação: o lockfile, o entity.lock ao lado da Recipe, o cache de fontes e todas as mensagens trazem a URL da fonte como você a escreveu.
Uma URL de fonte não traz credencial. Uma Recipe ou FeatureRecipe cuja url de fonte escreve um usuário antes do host — https://user:token@charts.example.com/…, ou um token escrito sozinho como https://token@charts.example.com/… — é recusada com E0361 quando o documento é lido, antes que qualquer coisa seja buscada: validar a Recipe a recusa, assim como todo pull, pin e build que a alcança. A mensagem nomeia o host e nunca a credencial: A source URL carries a credential (Uma URL de fonte traz uma credencial). Coloque a credencial em uma entrada machine do arquivo netrc em vez disso. Por SSH, um usuário escrito sozinho — ssh://git@github.com/… — nomeia uma conta e não um segredo e é aceito, enquanto uma senha escrita ali também é recusada.
A verificação lê apenas a parte da URL antes do host. Um token contido em uma query string ou em um caminho — …/index.yaml?access_token=… — não é detectado, então não escreva um ali: a URL é registrada como escrita no lockfile, no entity.lock e no cache de fontes, incluindo os nomes dos diretórios do cache.
Variáveis de ambiente
As configurações do workspace que o pull lê podem ser substituídas pelo ambiente, acima da configuração versionada e abaixo de qualquer flag: AGGREGA_OFFLINE (veja Offline, e --offline para o flag acima dela), AGGREGA_CATALOG_DIRS (separada como uma lista de caminhos do sistema operacional; forneça caminhos absolutos), AGGREGA_ARTIFACT_CACHE_DIR, AGGREGA_DEFAULT_REGISTRY e AGGREGA_SKIP_SIGNATURE_VERIFICATION (ruidosa — onde quer que um pull teria verificado uma assinatura, ele registra um aviso de que a verificação está desativada globalmente). Veja environment-variables.md para a lista completa e o modelo de precedência.
Veja também
- ./aggrega-build.md — verifica o lockfile e faz o pull automaticamente quando configurado.
- ./aggrega-serve.md — o daemon oferece essa mesma resolução em
aggrega/resolveDependencies, e dentro deaggrega/buildpara uma solicitação cujo campoautoPulla pede, de modo que um editor pode executá-la sem sair da sessão; em ambos os casos, ela só é executada quando uma solicitação a nomeia, e grava o mesmo lockfile que este comando. - ./aggrega-push.md — publica entidades de catálogo em um registry.
- ./aggrega-lint.md — a verificação de publicação que precede
aggrega push. - ../../architecture/13-catalog-and-registry.md — o modelo completo de catálogo, lockfile e cache.
Sinopse
aggrega pull [<uri>...] [flags]Descrição
Resolve the Release's catalog and source dependencies into the cache and write the per-Release lockfile.
By default, pull reconciles the lockfile against the current dependency resolution while honoringthe pins it already records. That pin discipline governs what a registry or the content cacheserves: such an entity is fetched at its pinned version and verified against its pinned digest,and if the registry no longer serves the pinned bytes, pull halts rather than silently re-pinning.An entity a local catalog directory supplies is resolved from that directory instead, at theversion its file declares, and its recorded pin is not consulted — so editing a pin by hand doesnot hold a locally-supplied entity at that version, and the reconcile rewrites the entry to matchthe file. A reference with no pin — newly added, or removed from the lockfile by hand — isresolved fresh and added. Entities no longer among the resolved dependencies are pruned.Re-running pull on an unchanged dependency set is a no-op.
Use --upgrade with no positional arguments to discard the existing lockfile and re-resolveevery entity from current registry state, floating each dependency to the highest availableversion. That form drops every recorded pin, so it asks for confirmation first; --yes answers inadvance, and on a non-interactive stdin it refuses rather than waiting for an answer nobody cangive. Pass one or more entity URIs after --upgrade to upgrade only those: each named pinis dropped and re-resolved fresh while every other pin — and the recorded external inputs —is held unchanged. A named target may also be a plugin that returns an accept-or-reject verdict;such a plugin carries no lockfile pin, and its identity is recorded beside the lockfile instead.Naming one the workspace still attaches adopts the identity it resolves to. Naming one theworkspace no longer attaches drops its recorded identity — the one way to clear an entry thatoutlived the attachment it was recorded for. A bare --upgrade does both for every plugin at once.A URI given without --upgrade is a usage error.
Each Recipe and FeatureRecipe this Release builds from one of your catalog directories carriesthe pins for its own inputs in the entity.lock beside it: a remote source: written out in full,a file an artifacts entry imports, and each file of a local source:. Recording them is theentity author's step, aggrega pin.By default pull records none of them, and halts on an entity whose lock is missing any, namingthe entity, each input and its class, and the command that records them. A local source's filesare held to their pins as one set: a file added, changed or removed since the pin halts the pullthe same way.Pass --pin-sources, or set pin_sources_at_pull in the workspace configuration, to have pull runthat same step instead; --pin-sources=false restores the halt for one run.
Which files of a local source directory belong to its entity was decided when the entity waspinned, by the ignore rules of the plugin that served its capability for the author, and itsentity.lock records that decision. Where the plugin this workspace binds for that capabilitydeclares different rules, pull prints a warning naming both plugins and the difference, andcarries on: the entity's files are the ones its recorded rules kept.Flags
| Flag | Padrão | Descrição |
|---|---|---|
--catalog | [] | Diretório de catálogo; repetível. Cada —catalog <dir> é colocado no início da pilha de busca do catálogo (a primeira correspondência vence): os catalog_dirs do workspace ou, para uma Release à qual a configuração do workspace atribui diretórios próprios em workspace.releases, os dessa Release; a pilha termina com o diretório chamado catalog na raiz do workspace, quando houver um. Uma lista catalog_dirs escrita vazia não lê nenhum catálogo local. |
--detail | false | Exibe, para cada entidade resolvida, o que este pull fez — obtida do zero de um registry, reutilizou um slot do cache, encontrada em um catálogo local, servida de dentro do binário do compilador, ou externa (o Aggregate ou o Manifest da própria Release, lido do arquivo ou da entrada que a Release indica). Apenas stdout; não é gravado no lockfile |
--dry-run | false | Resolve as dependências e exibe o que este pull gravaria em vez de gravá-lo: o caminho de cada arquivo e o conteúdo que ele teria vão para stdout, e o lockfile, o entity.lock ao lado de cada Recipe e FeatureRecipe cujos pins registrados mudariam com —pin-sources, e o registro de confiança de plugins ficam todos intactos. Apenas os arquivos que de fato mudariam são indicados. A resolução em si é executada exatamente como seria de outra forma, de modo que o cache de conteúdo ainda é preenchido, um pull que pararia diante de uma entidade sem pin também para aqui, e um —upgrade sem argumentos não pergunta nada porque não descarta nenhum pin — o que uma execução de teste mostra é o que um pull gravaria. Não é aceito com —verify, que já não grava nenhum deles |
--include-prerelease | false | Ainda não implementado: aceito e ignorado, de modo que um script que o passa continua funcionando quando ele começar a ter efeito |
--pin-sources | false | Executa a etapa de pin do autor da entidade sobre as Recipes e FeatureRecipes que esta Release constrói, registrando no entity.lock ao lado de cada uma o pin de cada entrada que ela lê — um source: remoto escrito por completo, um arquivo que uma entrada artifacts importa e cada arquivo de uma fonte local — em vez de parar diante de uma entidade cujo lock não os registra. É a mesma etapa que aggrega pin, gravando os mesmos bytes. Ela grava ao lado da entidade, então só é executada onde a entidade tem um local gravável: um documento em um dos seus diretórios de catálogo. Uma entidade resolvida a partir do cache não tem nenhum e nunca é fixada. Substitui o pin_sources_at_pull do workspace nas duas direções: —pin-sources fixa para esta execução e —pin-sources=false para nesta execução, independentemente do que diga a configuração |
--progress | false | Força a exibição do progresso do pull mesmo quando stderr não é um terminal, exibindo uma linha simples por etapa à medida que ela é concluída, com seu tempo. O padrão é auto: a checklist interativa de fases só é mostrada quando stderr é um terminal que interpreta sequências de escape, um terminal que não as interpreta recebe as mesmas linhas simples, e a saída redirecionada ou enviada por pipe não recebe nenhuma |
--quiet | false | Silencia a exibição do progresso do pull em stderr. Não afeta stdout. Tem precedência sobre —progress |
--release | — | Caminho para o arquivo YAML da Release (obrigatório). Um caminho relativo é resolvido em relação ao diretório em que você executa o comando, não em relação à raiz do workspace. Quando esse diretório não está em nenhum workspace e nenhuma raiz é informada, um caminho absoluto encontra o workspace a partir da pasta da própria Release |
--upgrade | false | Resolve novamente as dependências a partir do estado atual dos registries, levando cada uma à versão mais alta disponível. Sem argumentos (nenhum URI posicional), descarta o lockfile e resolve novamente todas as entidades, e pede confirmação primeiro porque descarta todos os pins registrados; com um ou mais URIs de entidades, resolve novamente apenas essas, mantendo inalterados todos os outros pins e as entradas externas registradas, e não pergunta nada (mutuamente exclusivo com —verify) |
--verify | false | Verifica o lockfile existente em relação à resolução de dependências que um pull faria agora, sem gravar o lockfile, o registro de confiança de plugins nem qualquer entity.lock; sai com código diferente de zero em caso de desvio ou de lockfile ausente. A resolução respeita os pins que o lockfile registra exatamente como um pull: uma referência cujo registry publicou uma versão mais recente desde o pull não é desvio, porque um pull manteria seu pin, e um registry que agora serve bytes diferentes sob uma versão fixada para a verificação como para um pull. O cache de conteúdo é lido e preenchido como um pull o lê e preenche: uma entrada que o cache contém sob seu pin é lida dali sem consultar um registry, uma que ele não contém é obtida, e uma que não corresponde mais ao seu pin é tratada exatamente como um pull a trata. Também confronta o entity.lock ao lado de cada Recipe e FeatureRecipe dos seus diretórios de catálogo que a Release alcança com aquilo com que um build o compara, e sai com código diferente de zero diante de um pin que um build recusaria: um arquivo importado que não corresponde mais ao seu digest registrado, uma fonte local cujos arquivos não correspondem mais aos seus digests registrados, ou um pin de fonte que discorda do lockfile. Também compara a assinatura que o lockfile registra para cada artefato, e o registro de confiança de plugins para cada plugin, com a que um pull registraria agora, e sai com código diferente de zero onde um pull registraria, substituiria ou removeria uma: uma assinatura que um requisito exige e que não está registrada, e uma feita para outro artefato, são relatadas sem consultar um registry, porque um pull as reescreve independentemente da resposta dele; uma assinatura que um pull busca novamente e poderia registrar inalterada — o artefato foi obtido, ou seu pacote de assinatura em cache foi removido ou alterado — é consultada em seu registry ou, no modo offline, deixada sem verificação com uma linha informando isso; e cada plugin que o registro de confiança de plugins abrange é verificado em seu registry, como todo pull o verifica, exceto no modo offline, em que é lido do cache de conteúdo como um build o lê, sua identidade e suas funções de host ainda são verificadas, e sua assinatura é deixada sem verificação com uma linha informando isso, a menos que um build o recuse por não registrar nenhuma ou por registrar uma feita para outro artefato, o que é relatado. Os marcadores de descontinuação não são comparados. Também relata as versões do compilador e dos plugins principais que o lockfile registra — relatadas para auditoria e nunca comparadas com este binário, de modo que uma diferença de toolchain nunca é desvio. Não é aceito com —pin-sources, qualquer que seja o valor fornecido: uma verificação não registra um pin que falta em um entity.lock nem para por causa dele, então o flag não mudaria nada (mutuamente exclusivo com —upgrade) |
--yes | false | Responde antecipadamente à confirmação do —upgrade sem argumentos, para uso não interativo. Ele afeta apenas essa confirmação e nada mais: qualquer outra forma de pull não pergunta nada, então passá-lo não muda nenhum comportamento nesses casos |