aggrega pull
aggrega pull resolve todas as dependências de uma Release e escreve um lockfile que fixa cada dependência numa versão exata e num digest de conteúdo. Um aggrega build posterior utiliza o que o lockfile fixa, verifica-o e para, nomeando tudo aquilo de que precisa e que não esteja aí fixado — pelo que os builds são reprodutíveis e capazes de funcionar offline.
Tudo o que um build consome é fixado neste único momento. As entidades do catálogo, os artefactos de origem para os quais uma Recipe aponta um provider e os documentos remotos que um provider pede enquanto renderiza são resolvidos pelo mesmo comando e registados na mesma escrita do lockfile. aggrega pull é o passo que toca na rede; o build não o faz. Esta é a regra completa, e o resto desta página é o que dela decorre.
O que faz
aggrega pull resolve três tipos de dependência numa única passagem:
- Entidades do catálogo — os Components, Features, Recipes, FeatureRecipes, bibliotecas de esquemas e de mapeamentos e plugins Wasm que a Release referencia, resolvidos transitivamente (através de
extends:,implements:,aggregate:, anexos de Feature e locais$import:/$ref:das bibliotecas) e obtidos do registo quando ainda não estão disponíveis localmente. - Artefactos de origem — o
source:remoto para o qual uma Recipe ou FeatureRecipe individual aponta um provider: um chart Helm (OCI ou HTTPS clássico) ou um fragmento Compose sobre HTTPS. Cada um é obtido, colocado em cache e fixado. - Entradas externas — os documentos remotos que um provider pede ao anfitrião enquanto renderiza, como um
$refnovalues.schema.jsonde um chart que aponta para um URL. Cada um é obtido, armazenado sob o seu digest de conteúdo e fixado.
Dois dos três são lidos a partir dos documentos que o utilizador escreveu. O terceiro não: as entradas externas são encontradas renderizando a Release, e é por isso que este comando renderiza uma. Executar o comando não exige nada disto — Como a resolução encontra as entradas externas descreve-o na íntegra, juntamente com o custo da renderização, o que acontece quando esta não consegue concluir e como um build que preenche o seu próprio lockfile se relaciona com ela.
Uma entidade do catálogo nomeada sem registo é obtida através do default_registry do espaço de trabalho, e um caminho de repositório que o predefinido inclua é o local de onde é obtida. Com default_registry: ghcr.io/acme, core/api-server é obtido de ghcr.io/acme/component/core/api-server — onde aggrega push o publica através do mesmo predefinido — e a sua assinatura é procurada aí. O caminho é apenas localização: a assinatura que um pull exige, as chaves e identidades em que confia e a credencial que apresenta são as guardadas para o anfitrião, pelo que a entrada registries de ghcr.io rege todos os caminhos nesse anfitrião. O lockfile regista uma entidade destas pela sua identidade, versão e digests, tal como regista uma obtida apenas de um anfitrião. A grafia de um caminho é explicada em como se escreve um anfitrião de registo.
Escreve o resultado em <release-stem>.lock, junto da Release. Um espaço de trabalho que anexa um plugin que devolve um veredicto de aceitação ou rejeição recebe também um segundo ficheiro nesse diretório — o registo de confiança de plugins.
Um pull a quem se pede que fixe escreve mais um tipo de ficheiro. Junto de cada Recipe e FeatureRecipe dos diretórios do catálogo que importe um ficheiro de artefacto, aponte para um source: remoto escrito por extenso ou leia um source: ao seu lado, fica um entity.lock que regista o digest desse conteúdo. Registá-lo é um passo do autor da entidade, aggrega pin, e por predefinição um pull não o executa: compara o lock de cada uma dessas entidades com o que o passo registaria e para onde falta uma fixação. aggrega pull --pin-sources, ou um espaço de trabalho que defina pin_sources_at_pull: true, executa o passo em vez disso — e então o efeito de um pull vai além do diretório onde a Release se encontra, embora os ficheiros de entidade escritos pelo utilizador nunca sejam alterados. O lock da entidade descreve esse ficheiro, e Pré-visualizar o que um pull escreveria mostra o conjunto completo para o espaço de trabalho antes de algo mudar.
Um pull recusado porque uma referência não resolveu para nada indica de onde são lidas as entidades locais, onde quer que seja executado. A recusa inclui a descrição, feita pelo próprio espaço de trabalho, dos diretórios de onde leu as entidades locais e do que alterar para que a entidade seja lida — a nota que De onde são lidas as entidades locais mostra — e inclui-a a partir deste comando, de um build que resolve primeiro as suas dependências, da ferramenta de pull de aggrega mcp e da resolução de dependências de um editor, porque a resolução que todos executam a compõe. A recusa da ferramenta de pull indica também o código curto e o código descritivo da condição, tal como um terminal imprime o código curto no início da recusa. Um ficheiro nesses diretórios que declare uma apiVersion do Aggrega — uma linha que começa, sem indentação, por apiVersion: e um valor iniciado por aggrega.ai/ — e que não pôde ser carregado, por exemplo um que não é analisado como YAML, é indicado na mesma recusa, entre os ficheiros de catálogo ignorados no carregamento, com o motivo dado pelo próprio analisador: um ficheiro assim pode ser o que declara a entidade que a referência indica, e nada pode ser lido dele que diga que entidade declara. Um ficheiro YAML que declare outra apiVersion, ou nenhuma, não é um documento do Aggrega e nunca é indicado aí.
O lockfile
O lockfile fixa cada dependência no seu URI, na versão resolvida e no digest de conteúdo. Tem secções para as entidades do catálogo, as bibliotecas de esquemas e de mapeamentos (cada uma com referências de volta para os Components e as Features que a consomem), os plugins Wasm, os artefactos de origem, as entradas externas (cada uma indexada pelo URL e com os plugins que a pediram) e os próprios ficheiros da Release. O ficheiro é escrito numa forma canónica e determinística.
Uma entidade é registada pelo que uma publicação dela transporta. O digest na linha de uma entidade abrange o seu documento e todos os ficheiros que nomeia ao seu lado — o source: local de uma Recipe ou FeatureRecipe, cada ficheiro que um $import: nomeia, o entity.lock ao seu lado, cada ficheiro de esquema que um Component ou uma Feature importa — o mesmo conjunto que aggrega push publica. Cada ficheiro contribui com o seu caminho e os seus bytes, e mais nada contribui: nem a forma como um arquivo foi comprimido, nem um carimbo temporal, nem um bit de permissão, incluindo o bit de execução. Uma entidade que não nomeia nenhum ficheiro é registada como esse único documento. Assim, a mesma entidade regista o mesmo digest quer tenha sido lida do diretório do catálogo do utilizador quer obtida de um registo, e um lockfile submetido a partir de um checkout é verificado noutro checkout do mesmo commit, qualquer que seja o seu umask e quer o sistema desse checkout registe ou não quais os ficheiros executáveis. Um chart editado sob uma Recipe, um ficheiro acrescentado a uma origem que ela declara e um entity.lock alterado mudam cada um o digest; um script cujo bit de execução mudou, e uma nota junto da entidade que nada nomeia, não o mudam. O Aggregate e o Manifest que a Release nomeia são registados da mesma forma, cada um como o seu único documento. Uma biblioteca é registada pelo digest dos seus bytes, que são o seu documento, seja de onde for que é lido.
Cada Recipe e FeatureRecipe que o Manifest vincula é uma linha, qualquer que seja o nível que a vincula. Uma realização que o nível name do Manifest escolhe para uma instância ou um anexo é adquirida e registada exatamente como uma que o seu nível type escolhe para todas as instâncias de um tipo, e o referenced_from da sua linha nomeia a entrada que a vincula — manifest.spec.mappings.components.name.<instance> ou manifest.spec.mappings.features.name.<attachment>. Um build compara-a com essa linha, pelo que um lockfile que não a registe faz parar o build, nomeando a realização e essa entrada. Consulte Mapeamento plano de URI para os dois níveis.
Os anexos de uma ligação são dependências exatamente como os de um componente. A Feature que um anexo numa ligação nomeia — escrito na entrada uses: de um componente no Aggregate, ou numa entrada de ligação na Release — é adquirida e registada como a Feature de um anexo escrito no próprio componente, e o referenced_from da sua linha nomeia a entrada de ligação que o autor escreveu, terminando em .uses.<socket>.<alias>.features.<slot>.type. A realização que o Manifest lhe vincula é também uma linha, quer seja features.type a vinculá-la, quer features.name indexado pelo nome do anexo, <alias>.<slot>. Um build compara ambas com as suas linhas: um lockfile sem uma delas faz parar o build, nomeando a referência e a entrada que a pede, e uma Feature cujo conteúdo mudou desde o pull fá-lo parar nomeando ambos os digests. Consulte a entrada de ligação do Aggregate para o próprio anexo.
Uma base que um Component ou uma Feature estende é uma linha, quer algo mais a nomeie quer não. O pull segue cada extends: até ao fim da sua cadeia e regista cada base sob o seu próprio tipo de entidade, com o referenced_from da sua linha a nomear o spec.extends da entidade que a estende — component(<name>:<version>).spec.extends. Um build lê a base dessa linha, pelo que um Manifest mapeia o tipo próprio de um wrapper e não precisa de nenhuma linha para a sua base. Uma base que nenhum diretório de catálogo, cache ou registo contém é reportada onde a cadeia é fundida — consulte-se An extends: chain cannot be assembled (Não é possível montar uma cadeia).
A Release é registada pelo seu conteúdo, e não apenas pelo seu nome. Tudo o que a Release pede — para que versão de chart uma origem resolve, que componentes ficam em que fronteira — é resolvido a partir do que o ficheiro contém, pelo que release_documents regista o digest da Release e de cada Release que ela estende, ao lado de release, que a nomeia. Se a Release for editada depois do pull, o build seguinte para antes de qualquer renderização, nomeando o ficheiro editado e indicando que se faça novo pull; um simples aggrega pull --release <release> regista a edição respeitando todas as outras fixações. O digest abrange os bytes do ficheiro tal como estão, pelo que uma alteração de um comentário ou de espaços em branco também conta, exatamente como no Aggregate e no Manifest. Um ficheiro que a Release importa através de parameters não é registado desta forma.
Um pull procura um marcador de descontinuação em cada artefacto cuja assinatura verifica, e indica o que encontrou. Um marcador cuja própria assinatura é verificada face a um signatário que o pull aceita — o próprio signatário do artefacto, ou uma identidade em trusted_deprecation_identities do registry — é registado e anunciado com a 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 — é reportado como marker present but not honored, com o motivo, e não é registado. Uma consulta que não pôde terminar — o pull não conseguiu abrir o registry do artefacto, ou a listagem do que lhe está anexado não respondeu — é reportada como marker lookup did not complete, com o motivo, e não regista nada, porque o pull nada apurou sobre a existência de um marcador. Num registry cuja própria política de confiança exige uma assinatura para o tipo do artefacto e não é advisory, qualquer um desses dois casos interrompe o pull em vez de ser reportado. Um artefacto sem marcador não produz nenhuma linha, e onde a verificação de assinaturas está desligada, para o espaço de trabalho ou para o registry do artefacto, não se procura nenhum marcador.
Submeta <release-stem>.lock juntamente com a Release, tal como se submete qualquer manifesto de dependências fixadas. Um diff do lockfile mostra aos revisores exatamente que versões e digests de dependências mudaram; uma alteração do digest de uma biblioteca nomeia os consumidores afetados.
O que um determinado pull fez — se cada entidade foi obtida de novo de um registo (fetched-fresh), reutilizou uma posição da cache (cache-reuse), foi encontrada num catálogo local (local), foi servida a partir da cópia dentro do binário do compilador (in-binary) ou era externa (external: o próprio Aggregate ou Manifest da Release, lido do ficheiro ou da entrada que a Release nomeia em vez de resolvido como uma das suas dependências; um Aggregate que o pull obteve de um registo é fetched-fresh) — é um diagnóstico transitório de evento de pull impresso no stdout por --detail, e nunca é escrito no lockfile. A origem que serviu uma entidade depende do estado local da máquina que faz o pull, pelo que persisti-la quebraria a identidade byte a byte do lockfile entre máquinas. Indica o que este pull fez, o que é irrecuperável depois (uma entidade obtida de novo fica em cache na execução seguinte); para o estado de resolução, após o pull, das dependências de uma Release, utilize 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 um source: remoto, um ficheiro que uma entrada artifacts — ou uma entrada de boundary.artifacts de uma Recipe — traz com $import, ou os ficheiros de um source: que nomeia um diretório ou um ficheiro ao seu lado. O digest de cada um deles é registado num ficheiro chamado entity.lock, no mesmo diretório que o ficheiro da entidade. O ficheiro da entidade escrito pelo utilizador nunca é alterado; o que dele deriva fica ao seu lado. O esquema do lock da entidade descreve o ficheiro campo a campo.
Quem o escreve. Um único passo o escreve: aggrega pin, que o autor da entidade executa, não precisa de nenhuma Release e regista todas as classes de fixação que o lock contém. aggrega pull --pin-sources e aggrega push --pin-sources executam esse mesmo passo em nome do autor e escrevem os mesmos bytes. Um pull a quem não se pediu que fixasse não escreve lock nenhum: para cada Recipe e FeatureRecipe que a Release constrói a partir dos diretórios do catálogo, compara o que o passo registaria com o que o lock contém e para onde falta uma fixação ou onde esta já não corresponde à sua entrada, nomeando a entidade, cada entrada e a sua classe, e aggrega pin. Os ficheiros de uma origem local são comparados com as suas fixações como um conjunto: um lock que não registe nenhum deles faz parar o pull, tal como um ficheiro acrescentado, alterado ou removido desde a fixação. A chave de espaço de trabalho pin_sources_at_pull torna a fixação a predefinição de todos os pulls, e --pin-sources=false repõe a paragem numa execução. Fixar é um dever de autoria, pelo que uma paragem no primeiro pull de um consumidor significa que o publicador da entidade nunca a fixou; a solução do consumidor é essa chave, e não uma edição manual do diretório de outra pessoa. aggrega pin explica isto na íntegra.
O que contém. Três listas, cada linha a nomear uma entrada:
sourceDigests— uma linha para cadasource:remoto cujas coordenadas foram escritas por extenso, sem modelo no seukind,url,chart,module_subdir,versionouref. A linha inclui okinde ourlda origem, o seuchartoumodule_subdirquando os tem, a versão para que resolveu — para uma origem git, o commit que o seurefnomeou — e o digest de conteúdo do arquivo obtido, mais o digest do manifesto para um chart obtido por OCI.artifactDigests— uma linha para cada entradaartifactsouboundary.artifactsfornecida por um ficheiro importado com$import, nomeando a entrada e o digest dos bytes do ficheiro. Uma entradaartifactsé nomeada pela sua chave, e uma entradaboundary.artifactscomoboundary/<key>, pelo que uma entrada de cada bloco escrita sob a mesma chave é fixada separadamente.localSourceDigests— uma linha para cada ficheiro com que umsource:que nomeia um diretório ou um ficheiro junto da entidade contribui para o que uma publicação da entidade transporta, nomeando o caminho do ficheiro junto da entidade e o digest dos seus bytes. Nada é obtido para uma origem destas; os seus ficheiros são processados tal como estão. Uma origem escrita como modelo contribui com todos os ficheiros do diretório da entidade, pelo que cada um deles tem uma linha.
O que não contém:
- Uma origem remota cujas coordenadas são preenchidas a partir de um modelo — uma
versionlida de.infra, por exemplo. O artefacto que ela nomeia é decidido por cada Release que utiliza a entidade, pelo que cada versão para que resolve é fixada no lockfile dessa Release, e nada sobre ela é escrito junto da entidade. - Uma entrada
artifactsouboundary.artifactsinline, que faz parte do ficheiro da entidade, e uma entrada retirada de uma ArtifactLibrary, cujo conteúdo é fixado pela versão da biblioteca que o lockfile regista.
Uma entidade sem nada para fixar não recebe entity.lock, e o passo, executado sobre uma entidade que já não precisa de um, remove-o.
Submeta-o junto da entidade. Todas as Recipes e FeatureRecipes usam o mesmo nome de ficheiro, e o diretório onde ele se encontra indica a que entidade pertence, pelo que o lock acompanha esse diretório. Não tem carimbo temporal e as suas linhas são mantidas numa ordem fixa, pelo que o passo sobre entradas inalteradas o deixa idêntico byte a byte, e um diff sobre ele nomeia a origem, o ficheiro importado ou o ficheiro da origem local que mudou. Um diretório contém um único lock, pelo que o passo recusa uma Recipe ou FeatureRecipe com qualquer outra entidade ao seu lado — todos os tipos têm um diretório próprio, exceto Aggregate, Release e Manifest — e um pull a quem se pede que fixe recusa uma entidade destas antes de resolver seja o que for; Uma entidade por diretório expõe a regra. Um pull que não fixa não escreve nada junto de uma entidade e não avalia o seu diretório.
aggrega build compara os ficheiros com ele. Um build lê o lock e faz três comparações:
- Cada ficheiro importado volta a ser processado e é comparado com a sua linha, um ficheiro de
boundary.artifactsexatamente como um ficheiro deartifacts. Um ficheiro editado depois de fixado faz parar o build com[CATALOG_ERROR E0026], nomeando o artefacto tal como a sua linha o nomeia, o ficheiro importado e ambos os digests. - Os ficheiros de uma origem local voltam a ser processados e são comparados com as suas linhas, como um conjunto, antes de o provider ler a origem. Um ficheiro editado, acrescentado ou removido desde a fixação faz parar o build com
E0305sob a instância de componente a que a origem pertence, nomeando cada um desses ficheiros e ambos os digests; um ficheiro junto da entidade com que a origem não contribui não é comparado. Um lock que não registe nenhuma linha para uma origem local não deixa nada para comparar, como descreve A local source no longer matches the pins recorded beside its Recipe (Uma origem local já não corresponde às fixações registadas junto da sua Recipe). - Cada linha de origem é comparada com o digest que o lockfile da Release regista para a mesma origem. Uma discordância faz parar o build com
[FETCH_ERROR E0135], nomeando o lock e ambos os digests. Os dois ficheiros são escritos por duas resoluções da mesma origem — a do passo de fixação e a do pull — pelo que discordam quando essas resoluções obtiveram bytes diferentes, ou quando um dos dois ficheiros foi editado. Bytes diferentes sob uma mesma versão é o aspeto de uma origem a montante que voltou a publicar uma versão.
Um lockfile escrito antes da alteração para primeiro, e um pull nomeia o ficheiro. O lockfile regista a entidade pelo que ela transporta, e o lock e todos os ficheiros que estas comparações leem fazem parte disso, pelo que um build — ou aggrega pull --verify — com um lockfile escrito antes de um ficheiro importado, um ficheiro de uma origem local ou o próprio lock mudarem para antes de qualquer das três comparações ser executada: The lockfile no longer matches what the release resolves to (O lockfile já não corresponde ao que a Release resolve), nomeando a entidade e ambos os digests. Um simples aggrega pull nomeia então o ficheiro, porque compara o lock com o que o passo de fixação registaria e recusa a entrada cuja fixação já não corresponde: An entity reads an input the lock beside it records no pin for (Uma entidade lê uma entrada para a qual o lock ao seu lado não regista fixação).
Onde o lockfile não tem registo do próprio conteúdo da entidade, as três comparações são o 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 regista o Component ou a Feature, pelo que nada no lockfile muda quando os ficheiros da Recipe mudam, e um build e um pull de verificação reportam o ficheiro alterado com o código acima. A comparação da linha de origem é também o que um build encontra quando a entrada source_artifacts do lockfile é o registo que mudou, enquanto o lock junto da entidade não mudou.
Responder à paragem. Se o ficheiro importado foi alterado de propósito, execute aggrega pin sobre a entidade: o passo regista o novo digest do ficheiro e o build seguinte aceita-o. Caso contrário, reponha o ficheiro. Uma origem local que mudou admite as mesmas duas respostas: fixar novamente a entidade ou repor os ficheiros que a paragem nomeia. Para uma linha de origem que discorda do lockfile, reponha entity.lock a partir do controlo de versões, ou execute aggrega pin sobre a entidade para o reescrever.
aggrega pull --verify também o verifica. Um pull de verificação faz as mesmas três comparações sobre os locks junto das Recipes e FeatureRecipes que a Release alcança nos diretórios do catálogo, reporta todas as fixações que um build recusaria, com o mesmo código e nas mesmas palavras, termina com código diferente de zero se houver alguma e não escreve nenhum lock.
Onde nenhum lock é comparado. Uma Recipe ou FeatureRecipe resolvida a partir de um registo, e não de um dos diretórios do catálogo do utilizador, não tem lock que um build leia; as suas origens são comparadas apenas com o lockfile da Release. E uma origem escrita num ref: git é registada no lock com o commit para que esse ref resolveu, enquanto um build procura a fixação da origem na versão que a entidade nomeia, pelo que essa linha nunca é comparada — nem por um build nem por um pull de verificação. O lockfile continua a fixar o commit, e todos os builds verificam o arquivo em cache em relação a ele.
O registo de confiança dos plugins
Alguns plugins que o espaço de trabalho anexa nunca moldam a saída renderizada. Um anexo plugins.governance numa função ir-verdict ou render-verdict, e todos os anexos plugins.linter, devolvem um veredicto de aceitação ou rejeição e nada mais — nenhum byte deles chega a um artefacto. Por isso não fazem parte do que um build reproduz byte a byte, e o lockfile, que fixa exatamente isso, é o sítio errado para eles.
As suas identidades vão, em vez disso, para um segundo ficheiro submetido: plugins-trust.yaml, junto do lockfile. Contém uma entrada por cada um desses plugins, que regista a coordenada de identidade do plugin, a versão selecionada para ele e o digest de conteúdo do artefacto resolvido — mais a assinatura que o pull verificou para esse artefacto, quando verificou uma, e, quando o publicador descontinuou esse artefacto depois de o publicar, o marcador que o pull encontrou e verificou. O esquema do registo de confiança de plugins descreve o ficheiro campo a campo.
Submeta plugins-trust.yaml juntamente com o lockfile, pela mesma razão por que se submete o lockfile: um registo mantido fora do controlo de versões é um registo que ninguém pode rever e com o qual nada pode ser comparado. Submetido, é uma declaração partilhada de qual o plugin para que cada um desses anexos resolveu, e um diff sobre ele nomeia a identidade que mudou.
O ficheiro só aparece quando há algo para registar. Um espaço de trabalho que não anexa nenhum plugin que devolva veredictos não resolve nenhuma identidade dessas, pelo que o pull não escreve ficheiro nenhum e não diz nada sobre ele — uma ausência, não um ficheiro em falta. Quando o pull o cria, nomeia o ficheiro criado e indica que deve ser submetido. Um pull posterior acrescenta uma identidade que o registo ainda não contenha e deixa todas as identidades já registadas exatamente como estão.
Todas as alterações a este ficheiro são anunciadas, e nada mais é. Um pull que altera o registo imprime uma linha por cada entrada alterada, nomeando o plugin e qual foi a alteração: uma identidade registada pela primeira vez, uma identidade adotada em lugar da existente (nomeando ambas, para que se veja o que foi trocado), uma descontinuação registada para o artefacto que uma entrada já nomeia, uma descontinuação retirada de uma entrada, uma assinatura registada para uma entrada ou dela retirada, ou a entrada eliminada. A linha de criação acima é separada e diz respeito ao ficheiro e não a uma entrada, pelo que uma primeira resolução diz ambas as coisas: este ficheiro é novo e tem de ser submetido, e estas são as identidades que agora contém.
Um pull que deixa o registo exatamente como estava não diz nada sobre ele. Assim, uma linha sobre este ficheiro significa que o ficheiro submetido mudou e que vale a pena ler o seu diff — o que aqui importa mais do que no lockfile. Tudo o que o lockfile fixa faz também parte do que um build reproduz byte a byte, pelo que uma alteração aí tem um segundo sítio onde aparecer; a identidade de um plugin de veredicto não tem nenhum. Este ficheiro é o único sítio onde fica escrita a troca de uma verificação.
aggrega pull --dry-run não anuncia nada disto, porque não altera nada. Em vez disso, lista o registo entre os ficheiros que escreveria, como descreve Pré-visualizar o que um pull escreveria.
Uma descontinuação é acrescentada a uma entrada que o registo já contém, e isso não é o mesmo que reescrevê-la. Se um publicador descontinuar um plugin em que já se confia, o aggrega pull seguinte regista o marcador na entrada existente desse plugin — a coordenada, a versão e o digest ficam intactos, porque o artefacto não mudou e nada de novo está a ser adotado. Assim, um simples pull pode acrescentar um bloco deprecation, e só uma atualização explícita altera alguma vez uma identidade. Um marcador só é registado para o artefacto que a entrada já nomeia, e nenhum pull persegue um que tenha deixado de ser publicado: um marcador registado só sai com a entrada que o continha, ou seja, quando essa entrada é eliminada, ou quando uma atualização explícita volta a resolver o plugin e não encontra nenhum marcador nos bytes que a entrada já regista.
A assinatura verificada é registada numa entrada da mesma forma, e cada pull responde-lhe de novo. O pull verifica a assinatura de cada um destes plugins em relação à política de confiança do seu registo em todas as execuções — um plugin servido por um registo é obtido pela sua versão de cada vez, já que nada o fixa — e regista o que verificou na entrada do plugin, mais uma vez sem tocar na identidade: o modo, o signatário que correspondeu e o digest do pacote de assinatura que colocou em cache, a mesma signature que uma entrada do lockfile contém. 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 tem nenhuma e nenhuma é exigida, ou skip_signature_verification ou um registo advisory o admitiu — a entrada não regista nenhuma. O pacote de assinatura verificado volta também a ser colocado em cache, e uma cópia em cache que já não corresponda ao seu digest é reescrita. Assim, uma entrada que perdeu a sua assinatura, uma entrada com uma assinatura copiada da de outro plugin, uma entrada cujo pacote de assinatura em cache foi removido ou alterado, ou um registo eliminado ou escrito antes de uma assinatura ser registada, é reparado pelo aggrega pull simples seguinte. Um build compara cada um desses plugins com esse facto: consulte O registo de confiança de plugins na página do build.
Uma identidade resolvida que discorda da registada faz parar o pull. Uma entrada registada nomeia uma versão e um digest, pelo que a mudança de qualquer um deles é o mesmo evento: o plugin que seria executado não é o plugin para o qual o registo foi revisto. O diagnóstico nomeia o plugin, o que o registo contém e o que esta resolução reportou, nos dois eixos ao mesmo tempo — e o pull para sem tocar no registo, pelo que a identidade revista continua lá para comparação. Para perante a versão sozinha (uma nova publicação cujos bytes não mudaram) exatamente como para perante o digest sozinho (um novo push na mesma versão).
aggrega pull --verify faz a mesma comparação. Não escreve nenhum dos ficheiros que um pull submete, pelo que não adota nada; reporta se esses ficheiros ainda descrevem o que um pull resolveria hoje, e o registo é um deles. Compara também a assinatura de cada entrada com a que a própria verificação do plugin pelo pull dá, e reporta uma entrada cuja assinatura um pull registaria, substituiria ou retiraria — e um plugin para o qual o registo não contém entrada, onde um build o recusa por não registar assinatura — como descreve Compara as assinaturas registadas, nos dois ficheiros.
Para adotar uma nova identidade, peça-a pelo nome: aggrega pull --upgrade --release <release> <plugin>, nomeando o plugin tal como o anexo do .aggrega-config.yaml o nomeia, sem sufixo de versão. Isso volta a resolver esse único plugin e reescreve a sua entrada, deixando intactas todas as outras dependências fixadas e todas as outras identidades registadas — e funciona mesmo que o plugin não tenha fixação no lockfile, porque um alvo nomeado pode também nomear um desses anexos. Um aggrega pull --upgrade simples, que volta a resolver todas as dependências, volta também a resolver e reescreve todas as identidades registadas. O mesmo faz aggrega build --upgrade, que executa um pull de atualização total simples e não tem forma de nomear um alvo único.
Para remover uma identidade, peça-o também pelo nome. Desanexar um plugin do .aggrega-config.yaml não limpa a sua entrada, e isso é deliberado: um aggrega pull simples nunca remove nenhuma. Execute aggrega pull --upgrade --release <release> <plugin>, nomeando o plugin tal como o registo o nomeia — a sua coordenada de identidade, que é a cadeia que a paragem abaixo imprime — e a entrada é eliminada, deixando intactas todas as outras dependências fixadas e todas as outras identidades registadas. Um aggrega pull --upgrade simples elimina todas as entradas que nenhum anexo de veredicto nomeie já, na mesma passagem que volta a resolver tudo o resto.
Eliminar a última entrada deixa o ficheiro no lugar e vazio, em vez de o apagar. Um registo vazio não contém nada, pelo que não fixa nada e não faz parar nada — o mesmo que não haver registo nenhum — e manter o ficheiro faz com que a remoção apareça no seu diff como uma remoção.
Um registo que não satisfaz o seu esquema faz parar todos os comandos que o leem — um build, um lint no âmbito da Release e um pull, incluindo um pull que não tem nada próprio para registar. Um registo esvaziado e um danificado são deliberadamente diferentes: esvaziar é a forma de remover a última entrada, e um registo esvaziado permanece silencioso, enquanto um ficheiro cujo conteúdo já não é analisável é uma falha e não um registo vazio — lê-lo como vazio faria de truncar o ficheiro uma forma de desligar a comparação. Reponha-o a partir do controlo de versões para recuperar as identidades revistas.
Um plugin servido a partir da cópia dentro do binário do compilador não é registado. O pull regista o que adquiriu — obtido de um registo, ou lido da cache — e nada é adquirido do binário: esses bytes são identificados pela versão do compilador que os contém, pelo que não há nenhuma resolução própria a registar. Anexar um plugin que o binário já contém não produz, portanto, nenhuma entrada para ele. Isso é o registo a manter-se restrito a artefactos adquiridos, não uma resolução que falhou.
Um build, um lint no âmbito da Release e uma validação no âmbito da Release comparam a configuração do espaço de trabalho com o registo. Antes de qualquer um desses anexos ser executado, aggrega build, aggrega lint --release e aggrega validate --release — e as mesmas operações alcançadas através de aggrega serve e aggrega mcp — comparam os anexos de veredicto que a configuração nomeia com as entradas que o registo contém. Um plugin cujo digest de artefacto resolvido não é o registado é recusado em vez de executado. Uma entrada do registo que nenhum anexo de veredicto configurado justifique faz parar a execução: uma verificação que foi revista e agora está ausente deixa uma saída indistinguível de uma saída que essa verificação aprovou, que é exatamente o que quem lê a saída não consegue ver. A paragem nomeia o plugin e oferece as duas soluções que diferem consoante a intenção — anexar novamente o plugin se a remoção foi um engano, ou executar a atualização explícita acima se foi intencional — e imprime essa atualização pronta a executar. A direção inversa — um anexo que o registo ainda não contém — é a primeira deteção descrita acima, e nenhuma das comparações para perante ela; o requisito de assinatura é a única exigência a que um anexo sem entrada não escapa. As mesmas três superfícies comparam cada plugin que leem da cache com a assinatura que a sua entrada regista, quando o carregam, como a página do build descreve para um build. Os âmbitos de lint de todo o catálogo e de uma única entidade não consultam nenhum registo.
Uma validação é comparada com o registo porque executa as mesmas verificações que um build executa. aggrega validate --release alcança todas as verificações que aggrega build alcança, exceto a escrita dos artefactos, incluindo os plugins de verificação — é isso que faz com que «isto valida» signifique o mesmo que «isto compila» — pelo que a identidade do plugin que executa é comparada com o registo exatamente como a de um build. Os outros âmbitos de aggrega validate não são comparados com ele: validar o catálogo inteiro, uma única entidade ou um binário de plugin não lê de todo os anexos de plugins do espaço de trabalho, pelo que nenhum plugin de veredicto é executado neles e não há nada para um registo controlar.
Comparar uma configuração com o registo estabelece presença e identidade, e nada além disso. Estabelece que todas as verificações que o registo nomeia continuam anexadas e que cada uma é executada a partir do artefacto registado para ela. Não estabelece que uma verificação executada devolveu sequer um veredicto, e um caso disso não é detetado em lado nenhum: um anexo cuja function nomeia uma exportação que o plugin declara, que não é a exportação de veredicto que o seu socket lê, e cuja saída não contém nenhum campo de nível superior fora da forma que esse socket espera — sendo o objeto vazio o caso mais simples — é executado, não devolve nada sobre que rejeitar e deixa passar o build. A sua saída é indistinguível da de uma verificação que aprova, e nenhuma comparação com o registo o pode notar, porque nada no registo está errado: o plugin executado é exatamente o registado, e simplesmente não executou nada. Dois casos vizinhos fazem parar, pelo que 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 com um campo de nível superior que a forma do socket não declara é recusada em vez de ser lida como uma lista de veredictos que por acaso está vazia. Assim, uma identidade registada não é por si só suficiente para que uma verificação tenha avaliado alguma coisa.
O digest registado rege os plugins que o espaço de trabalho resolve a partir da cache que aggrega pull preenche, e nada do que resolve de outra forma. Essa é a resolução que um anexo de veredicto normalmente segue — nada o fixa no lockfile, pelo que os seus bytes vêm da cache, e essa leitura é onde o digest resolvido é comparado com o registado. Um plugin de veredicto que o espaço de trabalho resolve de outra forma nunca chega a essa leitura, e é regido pelo que rege a forma como foi resolvido e não pelo registo: os bytes servidos a partir da cópia dentro do binário do compilador são identificados pela versão do compilador que os contém, um .wasm junto da sua entidade de catálogo é um ficheiro do próprio diretório de catálogo do utilizador, um caminho explícito no sistema de ficheiros é o caminho que o utilizador nomeou, e um plugin com uma fixação no lockfile é regido por essa fixação. A outra metade da comparação de uma configuração com o registo não tem esse limite: todas as entradas que o registo contém têm de continuar a ser justificadas por um anexo configurado, seja qual for a forma como esse plugin é resolvido. Assim, o registo estabelece que as verificações que nomeia continuam anexadas, seja o que for que as serve, e estabelece a identidade de artefacto das que são servidas a partir da cache.
Respeitar vs. atualizar
Por predefinição, aggrega pull respeita um lockfile existente: uma dependência já fixada resolve para a sua versão fixada exata (verificada em relação ao seu digest fixado), só as referências ainda não fixadas são resolvidas e acrescentadas, e as fixações de referências que a Release já não alcança são podadas. Assim, um novo pull de uma Release inalterada não faz nada — reproduz o mesmo lockfile byte a byte (incluindo generated_at). Acrescentar uma nova dependência, ou fazer pull depois de uma edição manual ter removido uma fixação, resolve apenas essa lacuna e deixa intactas todas as outras fixações.
Uma dependência que um novo pull lê da cache é registada exatamente como o pull que a obteve a registou. A sua linha mantém a versão, o digest de conteúdo e o manifest_digest — este último retirado do manifesto armazenado junto do conteúdo na cache — juntamente com a signature e a deprecation que esse pull verificou no registo. Nada disso volta a ser consultado enquanto um build aceitar a linha, e --detail reporta uma dependência destas como cache-reuse, pelo que um novo pull cujas dependências estejam todas em cache, sobre um lockfile que registe todas as assinaturas que a configuração de confiança exige e só assinaturas que um build aceita, escreve o mesmo lockfile quer o registo esteja acessível quer não.
Um novo pull volta a consultar uma assinatura exatamente onde um build recusaria a linha, e há duas linhas dessas.
- Uma assinatura exigida que o lockfile não regista. Onde a configuração de confiança exige uma assinatura para uma dependência que a cache serve e a linha do lockfile não regista nenhuma — a linha foi editada, o lockfile foi escrito de raiz sobre uma cache que um pull anterior preencheu, ou o requisito foi acrescentado depois do pull que escreveu a linha — o novo pull pede ao registo dessa dependência a sua assinatura, pelo digest do manifesto armazenado junto dela na cache, exatamente como faz para uma dependência que obtém, e regista a assinatura verificada na linha. Essa linha é a que um build recusa (No verified signature is recorded for an artifact that requires one (Não está registada nenhuma assinatura verificada para um artefacto que a exige)), pelo que fazer pull novamente é o que elimina essa recusa. Um registo que não anexe nenhuma assinatura, ou uma assinatura que a configuração de confiança não aceite, faz parar o novo pull tal como faz parar um pull que obteve a dependência. As definições que permitem a um pull admitir uma dependência sem assinatura deixam uma linha destas como está e não perguntam nada sobre ela:
skip_signature_verificationno nível superior, o mesmo interruptor na própria entrada do registo, exceto para um tipo que a política de assinatura de todo o espaço de trabalho exija, e um registo marcado comoadvisory. - Uma assinatura registada que um build não aceita. Onde a linha regista 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 feito para outro artefacto — um build recusa a linha, diga o requisito de assinatura o que disser (A cached signature bundle does not match the digest recorded for it (Um pacote de assinatura em cache não corresponde ao digest registado para ele), A recorded signature was made for a different artifact (Uma assinatura registada foi feita para um artefacto diferente)). Por isso, o novo pull volta a perguntar ao registo dessa dependência pela sua assinatura, diga o requisito o que disser, através da mesma verificação que recebe uma dependência que obtém: o que essa verificação confirma substitui a assinatura da linha, e o pacote que ela nomeia volta a ser colocado em cache, sendo reescrita uma cópia em cache que já não corresponda ao seu digest — pelo que a linha e a cache ficam com o que o pull que obteve a dependência deixou. Uma assinatura que a configuração de confiança não aceite faz parar o novo pull tal como faz parar um pull que obteve a dependência, e o mesmo faz um registo que não anexe nenhuma onde uma assinatura é exigida. Onde a verificação não regista nenhuma —skip_signature_verificationonde se aplica, que não pergunta nada, um registo que não anexa assinatura onde nenhuma é exigida, ou um registoadvisoryonde nada é verificado — a assinatura da linha é retirada, o que um build admite com as mesmas definições.
Uma linha cuja assinatura registada um build aceita não volta a ser consultada, nem uma linha que não regista nenhuma e para a qual nada exige assinatura.
Uma dependência nomeada sem registo, num espaço de trabalho que já não nomeia nenhum default_registry, não pode ser consultada. A sua linha foi associada a um registo pelo pull que registou a sua assinatura e, sem predefinido, não há registo a quem perguntar. Onde uma linha destas regista uma assinatura que um build não aceita, o novo pull para com a própria recusa do build, dizendo que não está configurado nenhum registo para voltar a consultar a linha, e deixa o lockfile como estava. Configurar como default_registry o registo de onde a dependência veio e fazer pull novamente repara-o.
O que esse respeito rege é o que um registo ou a cache serve. Uma entidade que um diretório de catálogo local fornece é resolvida a partir desse diretório, na versão que o seu ficheiro declara, e a entrada que o lockfile regista para ela não é consultada pelo caminho. O lockfile continua a registar essa entidade, pelo que ela aparece lá — mas editar essa entrada manualmente não mantém a entidade na versão escrita, e a reconciliação seguinte reescreve a entrada para corresponder ao ficheiro. Para alterar a versão de uma entidade fornecida localmente que uma Release resolve, edite o ficheiro do catálogo e não o lockfile.
Uma fixação nomeia bytes, não um local, pelo que uma entrada de cache que já não contém a sua fixação é ignorada em vez de merecer confiança. Uma entidade editada no local — um novo corpo sob a mesma version — deixa a cache de conteúdo com o corpo anterior sob esse nome e versão. Um diretório de catálogo é lido primeiro, pelo que uma entidade que um deles ainda fornece é fixada a partir do seu ficheiro e a entrada desatualizada nunca é lida. A renderização que o pull executa para descobrir as entradas externas da Release lê cada fixação como um build o faz, a partir do diretório de catálogo que contém os bytes fixados, e reporta a entrada que ignorou com o aviso que aggrega build imprime. Onde nenhum diretório de catálogo fornece a entidade e um registo está acessível, o pull obtém novamente a versão fixada, reescreve a entrada e indica-o no erro padrão, nomeando a entrada e ambos os 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 obtidos são comparados com a fixação como em qualquer obtenção sob uma fixação, pelo que um registo que sirva outros bytes sob essa versão faz parar o pull, como descrito abaixo. Onde 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 registo serve a versão fixada ou a execução não alcança nenhum — o pull e aggrega pull --verify param com E0135 — ou E0133 onde o manifesto da entrada de cache não é o que o lockfile fixa — nomeando cada origem que leram e o que continha; onde a execução não alcançou nenhum registo, a paragem nomeia também o passo que volta a obter a versão fixada.
Para atualizar as versões fixadas, execute aggrega pull --upgrade --release <release> — descarta as fixações existentes e volta a resolver todas as dependências para as versões mais recentes que satisfaçam os requisitos. Atualizar é o ato explícito; a predefinição nunca faz flutuar uma dependência fixada. Isto segue a convenção de npm ci / cargo / go build (a predefinição concretiza 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 mudando silenciosamente uma versão.
Essa forma simples elimina todas as fixações registadas, pelo que pede confirmação antes de fazer o que quer que seja. Responda-lhe antecipadamente com --yes para utilização não interativa; com a entrada padrão que não seja um terminal e sem --yes, recusa em vez de esperar por uma resposta que ninguém pode dar. Nomear alvos (aggrega pull --upgrade --release <release> <uri>) mantém todas as fixações não nomeadas, pelo que essa forma não pergunta nada. aggrega build --upgrade executa a forma simples e está sujeito às mesmas condições.
Se os bytes de uma versão fixada no registo já não corresponderem ao digest que o lockfile registou (uma violação de imutabilidade a montante), pull para com um erro de integridade em vez de adotar silenciosamente os bytes alterados — execute --upgrade para fixar de novo deliberadamente.
Verificar um lockfile sem o escrever
aggrega pull --verify --release <release> responde a uma pergunta: executar aggrega pull agora alteraria o lockfile, ou o registo de confiança de plugins junto dele? Executa a resolução que um pull executaria, compara com ela o lockfile e o registo e para antes de ser escrita qualquer coisa que um pull submete — o lockfile, o registo de confiança de plugins e todos os entity.lock ficam como estão. Termina com código diferente de zero se faltar o lockfile e perante qualquer diferença, nomeando cada uma. Os marcadores de descontinuação não são comparados, como descrito abaixo. É recusado juntamente com --upgrade, com --dry-run e com --pin-sources, qualquer que seja o valor dado a essa opção: uma verificação não regista uma fixação que falte num entity.lock nem para perante ela, pelo que a opção não mudaria nada.
Respeita as fixações registadas exatamente como um pull. Uma dependência que o lockfile fixa resolve na 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 vs. atualizar. Assim:
- Uma referência cujo registo publicou uma versão mais recente desde o pull não é desvio. Um pull manteria a sua fixação, pelo que o lockfile continua a ser o que um pull escreveria;
aggrega pull --upgradeé a forma de adotar a versão mais recente. - Um registo que agora serve bytes diferentes sob uma versão fixada faz parar a verificação com o erro de integridade que faz parar um pull, em vez de reportar a alteração como desvio.
- Uma linha do lockfile editada manualmente, uma Release editada e uma entidade editada num diretório de catálogo local são reportadas cada uma, porque cada uma é uma diferença entre o lockfile e o que um pull resolve agora.
Lê e preenche a cache como um pull. Uma entrada que a cache contém sob a sua fixação — uma entidade do catálogo, ou o .wasm de um plugin — é lida daí sem perguntar a um registo, o que permite executar uma verificação sob a postura offline sobre um espaço de trabalho que um pull ligado à rede preencheu. Uma entrada que a cache não contém é obtida, como um pull a obtém, e uma que já não corresponda à sua fixação é tratada exatamente como um pull a trata. Assim, uma verificação pode acrescentar à cache, e nunca altera uma fixação.
Compara as assinaturas registadas, nos dois ficheiros
A assinatura que um pull verificou para um artefacto faz parte do que escreve: a signature numa entrada do lockfile, e numa entrada de plugins-trust.yaml para um plugin anexado numa função de veredicto. Quando as fixações concordam, uma verificação compara cada assinatura registada com a que um pull registaria agora, e reporta cada uma que um pull registaria onde não há nenhuma registada, substituiria ou retiraria, sob A recorded signature is not the one a pull would record (Uma assinatura registada não é a que um pull registaria). Todas essas entradas, em qualquer dos ficheiros, são nomeadas na mesma execução.
As entradas do lockfile que consulta são a escolha do próprio pull. Um novo pull pergunta a um registo pela assinatura de uma entrada exatamente onde Respeitar vs. atualizar descreve, e uma verificação segue essa mesma escolha:
- Duas são reportadas sem perguntar a um registo, porque um pull reescreve-as seja qual for a resposta do registo: uma entrada servida pela cache que não regista assinatura onde a configuração de confiança exige uma — o pull regista a assinatura do artefacto, ou para onde não é possível estabelecer nenhuma — e uma entrada cuja assinatura registada foi feita para outro artefacto, que o pull substitui pela do próprio artefacto.
- Todas as outras entradas que um pull voltaria a consultar são perguntadas, porque só a resposta do registo diz se o pull as alteraria: uma entrada cujos bytes esta verificação obteve, e uma entrada cujo pacote de assinatura em cache foi removido, está ilegível ou foi alterado. A verificação pergunta ao registo, como o pull faria, e reporta a entrada onde a resposta regista, substitui ou retira a sua assinatura. O pacote de assinatura verificado é colocado em cache como um pull o coloca, pelo que uma entrada cujo pacote em cache foi removido, enquanto o seu registo ainda serve a assinatura registada, passa e deixa a cache reparada.
Uma entrada cuja assinatura registada um build aceita, e uma entrada que não regista nenhuma e para a qual nada exige assinatura, não são perguntadas, nem por um pull nem por uma verificação.
O registo de confiança de plugins é comparado com o mesmo pull. Cada pull verifica no respetivo registo a assinatura de cada plugin anexado numa função de veredicto, e o mesmo faz uma verificação, que reporta uma entrada cuja assinatura essa verificação registaria, substituiria ou retiraria. Um plugin para o qual o registo não contém entrada é reportado onde um build o recusa por não registar assinatura, porque um pull escreve uma entrada com a sua assinatura e o build recusa o plugin até lá. Qualquer outro é uma primeira deteção, que uma verificação não reporta, tal como não reporta nenhuma identidade que o registo ainda não contenha. Sob a postura offline, uma verificação não pergunta nada a nenhum registo sobre estes plugins, e Offline descreve o que reporta em seu lugar.
Os marcadores de descontinuação não são comparados. Um marcador anexado a um artefacto depois do pull é estado do registo, e muda sem que nada no espaço de trabalho mude; uma verificação que falhasse por causa dele falharia uma verificação sobre ficheiros em que o utilizador não tocou. Um marcador registado avisa um build em vez de o parar pela mesma razão. Assim, um pull pode registar um marcador numa entrada que uma verificação deixou passar.
Pré-visualizar o que um pull escreveria
aggrega pull --dry-run --release <release> resolve as dependências exatamente como um pull normal e depois, em vez de escrever, imprime o que teria escrito: um cabeçalho que nomeia o caminho de cada ficheiro, seguido do conteúdo que esse ficheiro conteria.
aggrega pull --dry-run --release release.yamlNomeia todos os ficheiros, não apenas o lockfile. O lockfile, o entity.lock junto de cada Recipe e FeatureRecipe cujas fixações registadas mudariam com --pin-sources, e o registo de confiança de plugins aparecem todos no mesmo relatório, porque uma pré-visualização que mostrasse apenas o lockfile ensinaria que o lockfile é tudo o que muda. Um pull que pararia perante uma entidade não fixada para também com --dry-run, pela mesma razão: o que uma pré-visualização mostra é o que o pull faria. Os ficheiros que um pull deixaria exatamente como estão, byte a byte, não aparecem de todo — um nome no relatório significa que esse ficheiro está prestes a mudar. A última linha conta-os, e um espaço de trabalho que um pull não alteraria reporta uma contagem de zero.
Nada no disco muda. Nenhum lockfile é escrito ou criado, nenhum lock de entidade é escrito ou removido, e nenhum registo de confiança é criado ou alterado. Onde uma capacidade é servida por mais do que um plugin provider e nada escolheu entre eles, a execução para, nomeando o que fornecer, em vez de oferecer escrever a escolha na configuração — uma pré-visualização não edita um ficheiro de configuração de passagem.
A resolução em si continua a ser executada, pelo que a cache continua a ser preenchida. As entradas externas que uma Release consome são um produto da sua renderização, e uma execução que se recusasse a resolver não teria nada para reportar, pelo que --dry-run obtém e armazena exatamente como um pull. O conteúdo sob .aggrega/cache só é lido através das fixações que um lockfile regista, pelo que preenchê-lo não altera nada do que um build resolve; o que uma execução de teste mostra é o que um pull escreveria.
Um --upgrade simples não pergunta nada com esta opção. A confirmação existe porque uma atualização total elimina todas as fixações registadas, e uma pré-visualização não elimina nenhuma — pelo que aggrega pull --dry-run --upgrade --release <release> é a forma a usar quando o que se quer saber é quanto custaria uma atualização, e é executada sem resposta.
Não é aceite com --verify, que já não escreve nenhum desses ficheiros. O par deixaria a opção sem fazer nada, embora parecesse ter feito algo, pelo que é recusado em vez de ignorado.
Há uma coisa que uma pré-visualização com fixação nem sempre consegue mostrar na íntegra, e indica-o quando acontece. Um pull a quem se pede que fixe reescreve o entity.lock junto de cada Recipe e FeatureRecipe e depois renderiza a Release para descobrir as suas entradas externas; uma pré-visualização deixa esses locks como estão, pelo que, onde uma fixação aí registada ficou desatualizada — editou-se um ficheiro importado desde que foi fixado, por exemplo — essa renderização é comparada com o digest desatualizado que o lock não escrito ainda regista, e para. Tudo o resto no relatório é exatamente o que um pull escreveria; só as fixações de entradas externas do lockfile reportado ficam incompletas. A execução indica-o tanto na saída como nos diagnósticos, em vez de entregar um lockfile que parece completo. Uma primeira resolução de um espaço de trabalho não é afetada, porque ainda não há nenhum digest registado em relação ao qual algo possa estar desatualizado.
A composição que estas fixações descrevem
Um lockfile fixa o que um build desta Release vai consumir, pelo que a resolução traça a composição que esse build traça: resolve os documentos, aplica as transformações que os anexos do espaço de trabalho declaram e submete o resultado às verificações que um build faz sobre um grafo terminado. Daí decorrem duas coisas, e ambas surgem na passagem que escreve o lockfile e não no primeiro build que o lê.
Uma composição que essas verificações rejeitam faz parar o pull. Uma aresta uses: cujo alvo não satisfaz o selector: do seu socket, uma Feature anexada a um componente que o seu appliesTo: não admite, e todas as outras violações que essas verificações reportam param este comando, com o diagnóstico que um build dos mesmos documentos imprime — e a paragem nomeia todas as constatações numa única execução, em vez de apenas a primeira, pelo que uma passagem entrega a lista completa a corrigir. Acontece antes da escrita, pelo que <release-stem>.lock e plugins-trust.yaml ficam exatamente como estavam e uma Release que não compila nunca é registada como uma que resolveu sem problemas. O que isto não abrange são os anexos que devolvem um veredicto: nenhum anexo ir-verdict ou render-verdict é executado aqui, pelo que um veredicto de rejeição para o build, o lint no âmbito da Release ou a validação no âmbito da Release que o despacha, e não este comando.
Um anexo numa função que molda o grafo é executado durante essa passagem, pelo que um plugin que não resolve faz parar o pull. Um anexo label-transform decide as etiquetas dos nós antes de algo ser comparado com elas, e um anexo annotation-transform injeta anotações que se expandem em anexos de Feature — ambos alteram o que o grafo contém, pelo que traçar o grafo significa despachá-los, e despachá-los significa ter os bytes de cada plugin. Um plugin cujos bytes esta passagem não consegue obter faz parar a execução, nomeando o plugin e o que não foi possível encontrar para ele — a mesma recusa que um build do mesmo espaço de trabalho faz quando não os consegue obter. O que despacha é a lista de anexos que esta passagem acabou de resolver, com as definições e os ficheiros de definição que o lockfile regista para que um build posterior a reconstrua, pelo que ambas as passagens executam o mesmo anexo sobre a mesma entrada.
Um Plugin que um passo de pipeline nomeia e que nada contém também faz parar 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, da cache de conteúdo ou do registo — e um que nenhum deles contém é um que um build também não conseguiria carregar. Assim, o pull para antes de escrever o que quer que seja, nomeando o Plugin e a Recipe ou FeatureRecipe cuja pipeline o nomeia, com a condição que um build levanta quando chega a esse passo (A plugin reference is not a Plugin entity (Uma referência de plugin não é uma entidade Plugin)). Isto aplica-se a todas as Recipes e FeatureRecipes que o Manifest vincula, incluindo uma que nada nesta Release anexa, porque cada uma é resolvida e fixada, quer seja renderizada quer não. Publique o Plugin, ou coloque-o num diretório de catálogo com o seu .wasm compilado ao lado, e faça pull novamente.
Essa paragem e uma execução degradada são resultados diferentes, deliberadamente. Uma renderização que não consegue terminar — a que Como a resolução encontra as entradas externas e Offline descrevem — deixa todas as fixações de dependências corretas, pelo que as fixações são escritas e a falta é reportada. Uma composição que as verificações rejeitam não é uma falta no que foi resolvido: é uma Release que não compila, pelo que nada é fixado para ela e a execução para.
A cache
O conteúdo obtido por pull é armazenado sob .aggrega/cache, dividido numa subárvore entities/ para as entidades do catálogo, numa subárvore source-artifacts/ para os artefactos de origem e numa subárvore inputs/ para as entradas externas que uma renderização consome. A posição de uma entidade do catálogo é nomeada pelo seu tipo, pela sua coordenada e pela sua versão — pelo que um Component e uma Recipe que partilham uma coordenada e uma versão mantêm duas posições —, a de um artefacto de origem pelo local de onde foi obtido, pela sua versão e por um prefixo do seu digest de conteúdo, e a de uma entrada externa pelo seu digest de conteúdo; o que um build lê de qualquer uma delas é verificado em relação ao que o lockfile regista. Fixações de versão idênticas partilham, por isso, uma única posição entre Releases. Cada posição de artefacto de origem contém o arquivo autoritativo, uma extração regenerada e um pequeno ficheiro de metadados; a extração é regenerada em cada leitura, pelo que a saída do build depende do arquivo e do lockfile, e não do estado dos ficheiros extraídos.
Todos os nomes que a cache deriva de um valor são aceites por Windows, Linux e macOS. Uma coordenada, uma versão, um anfitrião de registo ou um digest contêm caracteres que um nome de ficheiro não pode conter: a / entre as partes de uma coordenada, os : antes de uma versão, dentro de sha256: e antes da porta de um registo. Por isso, cada valor — um tipo, uma coordenada, uma versão, um anfitrião de registo ou um digest — é transcrito antes de se tornar um nome de diretório ou de ficheiro — uma letra minúscula, um algarismo, ., _ e - são escritos tal como são, e todos os outros caracteres são escritos como um escape iniciado por +. O Component core/devtool/adminer:1.0.0 na versão 1.0.0 é a posição entities/+zx000043omponent/core+zsdevtool+zsadminer+zx00003a1.0.0/1.0.0/, e uma posição nomeada por um digest de conteúdo é sha256+zx00003a<hex>. Uma letra maiúscula também é escapada, pelo que duas coordenadas que diferem apenas em maiúsculas e minúsculas mantêm duas posições num sistema de ficheiros que ignora essa diferença; um nome que o Windows reserva para um dispositivo, como con, tem a primeira letra escapada; e nenhum nome termina num ponto final. Dois valores diferentes nunca partilham 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 os seus nomes foram transcritos — uma entidade do catálogo pela sua coordenada, versão e tipo — e não pelos nomes transcritos.
Uma entrada de um arquivo mantém o nome que o seu publicador lhe deu, pelo que, no Windows, uma que o Windows não consiga conter é recusada. Os ficheiros que um artefacto de origem ou o arquivo de uma entidade do catálogo contêm são dispostos com os nomes que o arquivo lhes dá, não transcritos pela cache. Onde a extração é executada no Windows, uma entrada com uma parte que o Windows não consegue conter tal como está escrita — um nome que reserva para um dispositivo, como NUL ou aux, em maiúsculas ou minúsculas e com ou sem extensão, ou uma parte que termina num ponto final ou num espaço — é recusada com E0340, nomeando a entrada, e nada desse arquivo é disposto. Em Linux e macOS uma entrada destas é disposta tal como está nomeada. Uma entrada que sai do diretório da extração é recusada em todas as máquinas.
A posição de uma entidade do catálogo só é uma entrada com o seu manifesto. A posição contém o conteúdo que um registo serviu e, ao seu lado, o manifesto que descreve esse conteúdo. Uma posição que contenha apenas o conteúdo — uma obtenção que parou entre as duas escritas, ou um ficheiro lá colocado manualmente — não é uma entrada: um pull, e um pull de verificação, voltam a pedi-la ao registo da entidade onde for possível alcançar um, enquanto um build, que nunca obtém nada, trata a entidade como em falta, tal como um pull faz quando nenhum registo está acessível.
O que chega à cache é comparado com duas coisas: a forma que o próprio esquema da entidade descreve e o local que a cache lhe atribui. Um corpo obtido de um registo é submetido ao esquema do seu tipo — a mesma verificação que o volta a ler — antes de ser colocado em cache, pelo que uma entidade ou biblioteca publicada que o registo serve e que o seu próprio esquema recusa faz parar o pull, nomeando o que foi obtido, em vez de ser colocada em cache e encontrada mais tarde como uma falha. E um valor a partir do qual se constrói um local da cache e que colocaria um ficheiro em cache noutro sítio que não o local que o valor nomeia — uma versão que é um caminho e não uma versão, um caminho de url de origem ou um module_subdir que sobe acima do seu lugar — é recusado onde o local é construído, nomeando o valor ofensivo. Um valor escrito numa Recipe ou FeatureRecipe da autoria do utilizador é controlado da mesma forma no momento em que o local da cache é construído a partir dele — e o module_subdir de uma origem git mais cedo, antes de o repositório ser obtido, como 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 tal como está escrito — ../shared, ou ..\shared — é recusado antes de o repositório ser obtido, com E0307 a citar o valor, pelo que nada junto do checkout é lido. Uma ligação simbólica que o repositório submete é arquivada como o ficheiro ou diretório para que aponta, quando este se encontra dentro do repositório — o próprio module_subdir pode ser uma ligação dessas. Uma que conduza para fora do repositório faz parar o pull com E0321, nomeando a ligação e para onde conduz, e nada é colocado em cache, pelo que um repositório de onde se faz pull não pode levar o pull a copiar um ficheiro da máquina do utilizador para o artefacto. O checkout é removido quando o pull para, pelo que a mensagem nomeia a ligação 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 já não existe. Cabe ao repositório alterar a ligação. A fronteira do espaço de trabalho enuncia a regra que isto aplica.
A cache está ancorada ao espaço de trabalho e não ao diretório de onde o comando foi executado, pelo que um espaço de trabalho tem uma única 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 onde não foi encontrado nem nomeado nenhum espaço de trabalho é recusado antes de qualquer obtenção. Quando nada nomeia uma raiz e a deteção não ancora nada — a partir da pasta onde é executado ou, para uma Release nomeada por um caminho absoluto, a partir da própria pasta dessa Release — a pasta seria a raiz, e uma cache escrita sob ela torná-la-ia um espaço de trabalho. Por isso o pull para, não escreve nenhum lockfile nem nenhuma cache e nomeia a pasta e as duas saídas possíveis: nomear o espaço de trabalho com --workspace-root ou AGGREGA_WORKSPACE_ROOT, ou dar a essa pasta um .aggrega-config.yaml com um bloco workspace:. A ferramenta de pull de aggrega mcp, chamada sem workspace_root num servidor iniciado sem raiz, é recusada da mesma forma; Configuração lista os outros comandos a que isto se aplica.
Compilar onde a rede não está acessível
Como este comando é o único passo que acede ao exterior, uma execução com ligação à rede basta para tornar locais todos os builds posteriores. Essa execução escreve o lockfile e preenche a cache do espaço de trabalho com os bytes que essas fixações nomeiam, e um build não precisa então de mais nada além deles.
Três coisas viajam para a máquina desligada:
- A Release e o seu lockfile. Submeta
<release-stem>.lockjunto da Release; é o que indica ao build para que versão e digest cada dependência resolveu. plugins-trust.yaml, onde o espaço de trabalho anexa um plugin que devolve veredictos. Um build compara os anexos de veredicto que a sua configuração nomeia com esse registo antes de qualquer um deles ser executado, pelo que levar o registo é o que mantém o build desligado vinculado às identidades que foram revistas e às assinaturas que o pull verificou para elas. Submeta-o junto do lockfile, como descreve O registo de confiança de plugins.- O diretório da cache. As entidades, os artefactos de origem e as entradas fixadas residem todos sob ele, e tudo o que um diretório local
catalog_dirsnão forneça é lido daí.
Compile na máquina desligada como habitualmente. Definir aí a postura offline vale a pena, mesmo que um build sobre um lockfile preenchido leia o seu fecho a partir da cache: transforma uma possível tentativa de acesso à rede numa recusa imediata que nomeia a postura, em vez de uma tentativa de ligação que tem primeiro de esgotar o tempo limite. Tudo o que a cache não contém, e qualquer entrada externa que o lockfile não fixe, faz parar o build, nomeando o que falta e a resolução que o fixaria — nada é obtido silenciosamente para preencher a lacuna.
Uma máquina isolada por air gap e um espaço de trabalho offline são afirmações diferentes, e vale a pena manter a diferença. Uma máquina atrás de um air gap pode conter uma cópia local de um registo, ou um catálogo catalog_dirs com tudo o que precisa, caso em que um pull normal nessa máquina pode ser satisfeito sem aceder ao exterior. A postura offline descreve o que um comando pode procurar, não o que a máquina contém; Offline expõe o que recusa e o que deixa em paz.
Offline
Sob a postura offline — a chave de nível superior offline num ficheiro de configuração, AGGREGA_OFFLINE no ambiente, ou --offline na linha de comandos — aggrega pull recusa o acesso à rede. A recusa acontece antes de qualquer tentativa de ligação, e não como um tempo limite a meio de uma obtenção, pelo que um pull offline não alcança nenhum registo nem nenhuma origem remota. Onde um ficheiro submetido ou uma variável exportada definiram a postura e se pretende contorná-la num único comando, --offline=false permite a rede apenas nessa execução.
--upgrade é recusado liminarmente sob a postura, e é a única opção aqui que o é. Uma atualização total faz flutuar cada dependência para a versão mais alta que um registo oferece no momento, pelo que precisa de perguntar a um registo o que serve atualmente. Um pull normal não precisa: respeita as fixações que já regista, resolve apenas o que não tem nenhuma e pode, portanto, ser satisfeito com o que a máquina contém. A recusa indica qual dos três locais definiu a postura e como permitir a rede numa execução.
A resolução recorre então apenas ao que a máquina já contém: a pilha de pesquisa catalog_dirs e a cache sob .aggrega/cache. Perante um catálogo e uma cache que satisfaçam todas as referências, um pull offline termina normalmente e escreve um lockfile normal. O lockfile regista o URI, a versão resolvida e o digest de cada dependência, e nunca qual desses locais serviu os bytes — pelo que um pull offline e um pull online que resolvam as mesmas versões escrevem o mesmo lockfile.
Uma dependência que um pull offline não consegue satisfazer localmente fá-lo parar. A entrada nunca é ignorada:
- Uma entidade do catálogo que não resolve em lado nenhum faz parar o pull, nomeando a referência e o local de onde foi referenciada, pelo que tanto a dependência em falta como aquilo que a pediu são nomeados.
- Um
source:remoto faz parar o pull, nomeando a origem e indicando que se permita o acesso à rede ou que se preencha a cache a partir de um ambiente com ligação. - Uma dependência que a cache contém cuja assinatura exigida o lockfile não regista, ou cuja assinatura registada um build não aceita, faz parar o pull com a recusa offline, nomeando a dependência: registar a assinatura significa perguntar ao seu registo, como descreve Respeitar vs. atualizar. Permitir a rede nessa única execução regista-a. Uma assinatura registada que um build aceita não volta a ser consultada, pelo que não para um pull offline.
Uma entrada externa é a que não faz parar, e em vez disso indica-o. A renderização que as encontra não consegue obter o que ainda não está armazenado, pelo que um pull offline sobre uma Release com uma entrada externa não fixada termina, escreve todas as fixações de dependências que resolveu e reporta três coisas: que a renderização não terminou, o que fixou e que um build desta Release vai parar nomeando o URL. As fixações de dependências que escreveu estão corretas — nada nelas dependia da renderização — pelo que são mantidas em vez de deitadas fora para que alguém as reproduza.
Isto é deliberado, não uma lacuna, e não há nenhum interruptor para o alterar. Um pull que descartasse trabalho correto custaria a parte que teve êxito; um pull que ficasse calado entregaria um lockfile que parece completo e não está. Indicá-lo é o único resultado que permite agir: execute o pull novamente a partir de um ambiente com ligação, ou de um cuja cache já contenha o conteúdo, e o mesmo comando fixa-o.
Assim, um pull offline é uma recusa de tocar na rede, e não um resultado reduzido para tudo o que um documento nomeia, e para as entradas externas é uma resolução concluída que indica o que não conseguiu alcançar. Um lockfile que existe é um cuja resolução de dependências foi concluída; se as suas entradas externas estão completas é o que a própria saída do pull indica, e aquilo a que um build depois o vincula.
--verify sob a postura offline abrange menos, e reporta que o faz. Perguntar para onde aponta hoje um ref de origem registado significa alcançar o seu remoto, o que a postura offline recusa. Assim, um --verify offline verifica as dependências fixadas e salta esse eixo, imprimindo uma linha que o indica em vez de reportar uma correspondência que nunca estabeleceu. Uma assinatura registada que só o seu registo pode confirmar — numa entrada do lockfile cujo pacote de assinatura em cache foi removido ou alterado — é saltada da mesma forma, numa 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 registada que um pull reescreveria fosse qual fosse a resposta do registo continua a ser reportada offline, porque não é precisa nenhuma resposta para o saber, como descreve Compara as assinaturas registadas, nos dois ficheiros.
Um plugin anexado numa função de veredicto e servido por um registo é onde uma verificação offline e um pull offline se separam. Um plugin destes nunca é fixado no lockfile, pelo que cada pull resolve o seu .wasm a partir do seu registo, e um pull offline sobre um espaço de trabalho que anexe um para aí, nomeando o plugin como um cujo .wasm não conseguiu resolver — mesmo que a cache de conteúdo o contenha, e quer esse registo esteja marcado como advisory ou salte a verificação de assinaturas quer não. Uma verificação offline, em vez disso, não pergunta nada ao registo sobre o plugin: lê o plugin da cache de conteúdo, como um build o lê, e para onde a cache não contém o seu .wasm ou contém um que já não corresponde ao digest que o seu manifesto publicado nomeia. Continua a comparar a identidade do plugin com o registo de confiança de plugins e a voltar a verificar as suas funções de anfitrião em relação a esse .wasm, e para onde qualquer uma discorde, exatamente como uma verificação com ligação. Reporta o plugin onde um pull reescreve a sua entrada fosse qual fosse a resposta do registo, que é onde um build recusa o plugin por causa da sua entrada: por não registar assinatura, porque a sua entrada não regista nenhuma ou o registo não contém entrada para ele, ou porque a assinatura que a sua entrada regista foi feita para outro artefacto, que o pull substitui pela do próprio plugin. Todas as outras entradas — uma cuja assinatura um build aceita, e uma cujo pacote de assinatura em cache foi removido ou alterado — são nomeadas numa linha que diz que a sua assinatura não foi verificada, e não reporta 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 com ligação substituiria ou retiraria — uma cujo signatário foi editado manualmente, por exemplo, ou uma que o seu registo já não anexa — sendo essa linha a única coisa que o indica. Uma verificação em ambiente isolado continua disponível; o que não indica é se um ref mudou entretanto, ou se uma assinatura saltada seria registada de novo. Uma verificação que leia apenas o código de saída só cobre esses casos quando a verificação é executada com ligação.
Integração com aggrega build
- Verificação.
aggrega buildverifica cada dependência resolvida em relação ao lockfile e para perante um desvio: uma entidade, uma biblioteca ou um plugin cujo conteúdo já não corresponde à sua fixação, uma referência que a Release agora alcança e que o lockfile não fixa, ou uma que fixa e que a Release já não alcança, e um ficheiro de Release editado desde o pull. Executeaggrega pull --release <release>, o comando que a paragem imprime, para o resolver: o pull resolve a Release tal como está agora, reescreve as fixações que mudaram e mantém todas as outras, pelo que nada flutua que o utilizador não tenha alterado. Onde o que mudou é um ficheiro sob a origem local de uma Recipe, o pull nomeia primeiroaggrega pinpara essa entidade, como descreve O lock da entidade. Um lockfile que este comando acabou de escrever passa essa verificação, porque o comando executa a mesma verificação antes de o escrever; um build que pare 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 espaço de trabalho editada entre ambos — pelo que deve executar os dois sobre as mesmas.aggrega validate --releasee todas as seleções deaggrega inspectque resolvem uma Release submetem o lockfile à mesma verificação e recusam com a mesma paragem, pelo que nenhum deles deixa passar um lockfile que um build recusa. - Pull automático. Se faltar o lockfile e
auto_pullfor verdadeiro,aggrega buildexecuta primeiro o pull automaticamente. Seauto_pullfor falso, que é a sua predefinição, o build para e pede que se faça pull. O pull que um build executa seguepin_sources_at_pull, pelo que, perante uma entidade não fixada, para exatamente como um pull. O passo de pull que um build executa é o mesmo que esta página descreve, pelo que um build que preenche um lockfile existente para perante um ref de origem que mudou exatamente comoaggrega pull— consulte Determinismo e integridade. - Offline. Sob a postura offline,
aggrega buildutiliza apenas o que a máquina já contém, e recusa o acesso à rede antes de qualquer tentativa de ligação. Uma referência cujo conteúdo a cache não contém faz parar o build em vez de falhar a meio de uma obtenção, e um build sem lockfile a quem não se pede que preencha um para, nomeando o pull que o preencheria, exatamente como online.--auto-pullnão é recusado: o preenchimento que pede é o pull que esta página descreve, pelo que, sobre entidades do catálogo já em cache ou presentes num catálogo local, escreve o lockfile sem alcançar um registo — uma Recipe cujo chart é obtido de uma origem remota é resolvida novamente, pelo que offline para mesmo onde a 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 regista, ou cuja assinatura registada um build não aceita — fá-lo parar com a própria recusa do pull, nomeando essa referência.--upgradeé recusado, pela razão que Offline indica. - Pesquisa no catálogo. O pull respeita
catalog_dirsde.aggrega-config.yamlmesmo quando não é dado nenhum--catalog— e os diretórios próprios de uma Release, onde a configuração lhe atribui alguns sobworkspace.releases— e resolve a mesma pilha de pesquisa em que a primeira correspondência ganha queaggrega buildresolve, pelo que as dependências que 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 de qualquer resolução ou escrita, indicando a entrada e o ficheiro de configuração e a linha que o listam, como mostra De onde são lidas as entidades locais.
Como a resolução encontra as entradas externas
Nada nesta secção altera a regra acima — continua a haver um único momento em que algo é fixado, e é este comando. O que descreve é a forma como o comando alcança o terceiro dos três tipos, o que importa ao integrar a resolução num pipeline, ao ler uma execução que se degradou ou ao raciocinar sobre a razão por que este comando renderiza.
Uma entidade do catálogo e um artefacto de origem são cada um nomeados num documento; uma entrada externa não. Resolver os dois primeiros é questão de ler o que o utilizador escreveu. Uma entrada externa é nomeada por um provider, a meio de uma renderização, e os URLs que nomeia decorrem dos valores a renderizar — uma entrada de valores ausente deixa uma subárvore inteira do esquema de um chart por compilar e todas as referências remotas nessa subárvore por pedir. Nenhuma leitura da Release consegue enumerar o conjunto.
Assim, o comando faz duas coisas numa única passagem: resolve e fixa o fecho que os documentos nomeiam e depois renderiza esse fecho para ver que documentos remotos os providers pedem. Os artefactos renderizados são descartados e as fixações mantidas. Ambas as coisas são internas ao único comando, e nenhuma é um segundo momento em que algo possa ser fixado — há uma única escrita do lockfile, e ela contém todas as fixações.
Vale a pena conhecer duas consequências antes de integrar a resolução num pipeline automatizado como um passo barato. Custa mais do que uma resolução que apenas lê documentos, porque renderiza. E pode falhar por uma razão que uma resolução só de documentos não poderia: um provider que não consegue renderizar esta Release. Quando isso acontece, as fixações de dependências são escritas na mesma, porque nada nelas dependia da renderização, e o diagnóstico nomeia a fase que parou, o que foi fixado e que um build vai parar nomeando o URL não fixado. A execução não se perde, e Offline mostra o mesmo resultado alcançado de outra forma.
A renderização também compara o lockfile com a comparação que um build aplica, antes de qualquer escrita. Executa a própria sequência do build, pelo que compara o lockfile que este comando está prestes a escrever com aquilo para que um build da mesma Release resolve, exatamente como um build compara um lockfile que encontra no disco. Um lockfile que essa comparação recuse não é escrito — nem nada do que o comando teria escrito depois dele — 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 nomeou. Nada nos ficheiros do utilizador pode causar isso, e resolver novamente chegaria à mesma discordância, pelo que deve reportá-lo juntamente com a Release em vez de tentar de novo. É a única falha de renderização que impede a escrita, e é por isso que um build da mesma Release, sobre as mesmas entradas, não reporta desvio num lockfile que este comando escreveu.
Não há nenhum interruptor para saltar a renderização. Um interruptor desses preservaria como opção exatamente a surpresa que um momento único elimina: uma Release que resolve sem problemas enquanto uma entrada de que a sua renderização precisa fica por fixar, descoberta apenas na altura do build.
--auto-pull integra esta mesma resolução num 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, pelo que um build de um só comando custa a mesma renderização que custa um build normal sobre um lockfile preenchido. aggrega build explica quais das opções de renderização de um build chegam até ela.
O conjunto decorre dos parâmetros da Release, que é como as fixações de componentes já se comportam. Editar os parâmetros de uma Release entre a resolução e o build é uma edição à Release, pelo que o build para na comparação de desvio, nomeando o ficheiro, antes de qualquer renderização poder pedir um URL não fixado; a solução é este comando. Os parâmetros importados de um ficheiro separado não são registados pelo conteúdo, pelo que editar esse ficheiro chega à renderização, que para nomeando o URL não fixado — com a solução a nomear também este comando.
Determinismo e integridade
O source: de uma Recipe pode definir a sua versão por modelo a partir de values e infra resolvidos da Release (e sobre locals definidos no mesmo); estes resolvem na altura do pull e o resultado é fixado. O pull avalia apenas as entradas locals: que os campos source: leem, e as entradas que estas por sua vez leem, apenas com as funções auxiliares de modelo do próprio Aggrega: uma entrada que a origem lê e que chama uma função Sprig faz parar o pull, nomeando 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 a Recipe é renderizada — consulte Resolving a source: coordinate registers a narrower function set (Resolver uma coordenada regista um conjunto de funções mais restrito). Uma tag ou ramo Git mutável é fixado no commit concreto para que aponta, e o ref escrito pelo utilizador é registado ao seu lado. Na altura do build, o digest do arquivo em cache é verificado novamente em relação ao lockfile, pelo que uma cache adulterada é detetada.
Um ref registado é vinculado ao commit que fixou. O ref é registado porque execuções posteriores voltam a consultá-lo, e não por legibilidade — um build pergunta que artefacto nomeia, e um pull pergunta se ainda aponta para onde apontava. Um pull que não seja uma atualização volta a perguntar para onde aponta cada ref registado, e um ref que mudou no seu remoto faz parar a execução — nomeando o artefacto, o ref, o commit que o lockfile fixa e o commit para que agora resolve — em vez de adotar a mudança. Execute aggrega pull --upgrade --release <release> para a adotar. Uma atualização dirigida, que nomeia URIs de entidades, não o faz: uma referência de origem não é uma entidade que se possa nomear, pelo que uma execução dirigida a mantém exatamente como um pull simples.
Essa verificação é a única coisa que a nova verificação do digest na altura do build não pode fazer pelo utilizador. Um pull que adotasse um ref alterado reescreveria os bytes obtidos e o digest registado no mesmo ato, pelo que os dois valores que um build compara teriam mudado juntos e concordariam — e estar-se-ia a compilar um conteúdo de origem diferente daquele em relação ao qual o lockfile foi revisto, sem que nada o reportasse.
Só um ref que o lockfile regista é vinculado desta forma, e um ref é registado sempre que o utilizador escreve um. Uma Recipe que nomeia a sua origem apenas por version: não tem ref, pelo que não há nada que uma execução posterior volte a perguntar — que é a resposta certa, porque uma versão escrita pelo próprio utilizador não pode mudar sem o seu conhecimento. A referência do lockfile indica o que é registado.
Escreva o ref, não o commit. Um build encontra um artefacto de origem git pelo ref escrito pelo utilizador, comparado com o ref que o lockfile registou, pelo que ref: v1.2.3 compila com o commit em que essa tag foi fixada e o commit nunca tem de aparecer na Recipe. Nomear em vez disso uma tag mutável em version: não funciona e não é suposto funcionar: version: é comparado tal como está escrito, e para uma origem git o lockfile fixa um commit.
O lockfile fixa o conteúdo obtido de registos e de origens remotas, e regista o digest de cada entidade que resolve a partir dos diretórios do catálogo do utilizador — sobre o ficheiro da entidade e todos os ficheiros que nomeia ao seu lado, como descreve O lockfile — e de cada ficheiro de Release que a resolução leu. Os ficheiros de uma origem que começa por ./ ou ../, e um ficheiro de artefacto que uma entidade importa, são também fixados um a um no lock junto dessa entidade, como descreve O lock da entidade, que é o que nomeia aquele que mudou; a integridade do resto do espaço de trabalho entre builds é responsabilidade do sistema de controlo de versões. Consulte saída idêntica byte a byte para o âmbito da garantia de determinismo.
Autenticação
As credenciais de registo são lidas apenas a partir 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, juntamente com qualquer auxiliar de credenciais ou porta-chaves do sistema operativo para o qual o ficheiro delegue através de credsStore ou credHelpers. aggrega login <registry> escreve aí uma credencial, tal como docker login <registry>; execute qualquer um deles antes de aggrega pull para um catálogo OCI ou um registo de charts privado. Os ficheiros que podman login e helm registry login escrevem não são lidos.
Uma configuração de credenciais que não pode ser lida é reportada sem o que contém. Quando config.json não é JSON válido, o valor auth de uma entrada não é um utilizador e uma palavra-passe unidos por dois pontos e codificados em base64, ou um credential helper que o ficheiro nomeia não consegue responder, o acesso ao registo falha com uma mensagem que nomeia o registo e o ficheiro de credenciais, nunca o que o ficheiro ou a entrada contém. aggrega login e aggrega logout reportam da mesma forma um config.json que não é JSON válido, e não alteram nada nele. Corrija o ficheiro; 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 alcançado por HTTP ou HTTPS (git-repository) autenticam-se com o ficheiro netrc, o ficheiro de credenciais por utilizador que o curl e o Git também leem. É o único armazenamento de credenciais que estes três tipos leem: ~/.config/helm/repositories.yaml e os auxiliares de credenciais do Git não são lidos. Um repositório Git alcançado por SSH autentica-se através do agente SSH e não lê nenhum ficheiro netrc.
machine charts.example.com login deploy-bot password <token>Que ficheiro é lido. O ficheiro que a variável de ambiente NETRC indica, quando está definida. Caso contrário, .netrc no diretório pessoal; no Windows, _netrc em %USERPROFILE% quando esse ficheiro existe, e .netrc aí quando não existe. Um ficheiro em falta não contém credenciais e não é um erro. Um ficheiro que existe e não pode ser lido, ou que não segue o formato netrc, interrompe o comando com E0360, nomeando o ficheiro — e, para uma falha de formato, a linha — mas nunca o que o ficheiro contém: The netrc file cannot be read (O ficheiro netrc não pode ser lido). No Linux e no macOS, um ficheiro netrc que outros utilizadores da máquina possam ler gera um aviso que o nomeia; torne-o legível apenas pelo próprio utilizador (chmod 600).
Que entrada responde a um pedido. Cada pedido é procurado pelo seu anfitrião — o nome do anfitrião sem a porta, sem distinguir maiúsculas de minúsculas — e é respondido pela primeira entrada machine que nomeia esse anfitrião, ou pela entrada default quando nenhuma o nomeia. O login e a password da entrada são enviados como credenciais HTTP basic, tanto em http como em https; uma entrada a que falte qualquer um deles não envia nada. Um repositório cujo índice coloca os seus charts noutro anfitrião é respondido pedido a pedido: o pedido do índice usa a entrada do anfitrião do repositório, e o pedido do chart a do anfitrião do chart. Um pedido feito sem credencial tem de poder ser lido anonimamente, e um servidor que responda 401 ou 403 interrompe o pull como uma obtenção não autorizada, cuja solução nomeia a entrada a acrescentar e o ficheiro em que foi procurada.
A credencial não é escrita em lado nenhum. É lida quando uma obtenção é executada e enviada com o pedido: o lockfile, o entity.lock junto da Recipe, a cache de origens e todas as mensagens contêm o URL da origem tal como foi escrito.
Um URL de origem não contém credenciais. Uma Recipe ou FeatureRecipe cujo url de origem escreve um utilizador antes do anfitrião — 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 de qualquer obtenção: a validação da Recipe recusa-a, tal como todos os pulls, fixações e builds que a alcancem. A mensagem nomeia o anfitrião e nunca a credencial: A source URL carries a credential (Um URL de origem contém uma credencial). Coloque antes a credencial numa entrada machine do ficheiro netrc. Em SSH, um utilizador escrito sozinho — ssh://git@github.com/… — nomeia uma conta e não um segredo e é aceite, enquanto uma palavra-passe escrita aí é também recusada.
A verificação lê apenas a parte do URL antes do anfitrião. Um token contido numa query string ou num caminho — …/index.yaml?access_token=… — não é detetado, por isso não o escreva aí: o URL é registado tal como está escrito no lockfile, no entity.lock e na cache de origens, incluindo os nomes dos diretórios da cache.
Variáveis de ambiente
As definições do espaço de trabalho que o pull lê podem ser substituídas através do ambiente, acima da configuração submetida e abaixo de qualquer opção: AGGREGA_OFFLINE (consulte Offline, e --offline para a opção acima dela), AGGREGA_CATALOG_DIRS (separada como lista de caminhos do sistema operativo; forneça caminhos absolutos), AGGREGA_ARTIFACT_CACHE_DIR, AGGREGA_DEFAULT_REGISTRY e AGGREGA_SKIP_SIGNATURE_VERIFICATION (ruidosa — onde quer que um pull tivesse verificado uma assinatura, regista um aviso de que a verificação está globalmente desativada). Consulte environment-variables.md para a lista completa e o modelo de precedência.
Ver também
- ./aggrega-build.md — verifica o lockfile e faz pull automático quando configurado.
- ./aggrega-serve.md — o daemon disponibiliza esta mesma resolução em
aggrega/resolveDependencies, e dentro deaggrega/buildpara um pedido cujo campoautoPulla peça, para que um editor a possa executar sem sair da sessão; em qualquer caso, só é executada quando um pedido a nomeia, e escreve o mesmo lockfile que este comando. - ./aggrega-push.md — publica entidades do catálogo num registo.
- ./aggrega-lint.md — a verificação de publicação que precede
aggrega push. - ../../architecture/13-catalog-and-registry.md — o modelo de catálogo, lockfile e cache na íntegra.
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 | Predefinição | Descrição |
|---|---|---|
--catalog | [] | Diretório de catálogo; repetível. Cada —catalog <dir> é colocado no início da pilha de pesquisa de catálogos (a primeira correspondência prevalece): os catalog_dirs do espaço de trabalho ou, para uma Release à qual a configuração do espaço de trabalho atribui diretórios próprios em workspace.releases, os dessa Release; a pilha termina com o diretório chamado catalog na raiz do espaço de trabalho, quando existe. Uma lista catalog_dirs escrita vazia não lê nenhum catálogo local. |
--detail | false | Imprimir, por cada entidade resolvida, o que este pull fez — obtida de novo de um registo, reutilizou uma posição da cache, encontrada num catálogo local, servida a partir do interior do binário do compilador, ou externa (o próprio Aggregate ou Manifest da Release, lido do ficheiro ou da entrada que a Release nomeia). Apenas stdout; não é escrito no lockfile |
--dry-run | false | Resolver as dependências e imprimir o que este pull escreveria, em vez de o escrever: o caminho de cada ficheiro e o conteúdo que conteria vão para o stdout, e o lockfile, o entity.lock junto de cada Recipe e FeatureRecipe cujas fixações registadas mudariam com —pin-sources, e o registo de confiança de plugins ficam todos intactos. Só são nomeados os ficheiros que realmente mudariam. A resolução em si é executada exatamente como seria de outra forma, pelo que a cache de conteúdo continua a ser preenchida, um pull que pararia perante uma entidade não fixada para também aqui, e um —upgrade simples não pergunta nada porque não elimina nenhuma fixação — o que uma execução de teste mostra é o que um pull escreveria. Não é aceite com —verify, que já não escreve nenhum deles |
--include-prerelease | false | Ainda não implementado: aceite e ignorado, para que um script que o passe continue a funcionar quando começar a ter efeito |
--pin-sources | false | Executar o passo de fixação do autor da entidade sobre as Recipes e FeatureRecipes que esta Release constrói, registando no entity.lock junto de cada uma a fixação de todas as entradas que lê — um source: remoto escrito por extenso, um ficheiro que uma entrada artifacts importa e cada ficheiro de uma origem local — em vez de parar perante uma entidade cujo lock não as regista. O mesmo passo que aggrega pin, escrevendo os mesmos bytes. Escreve junto da entidade, pelo que só é executado onde a entidade tem um local gravável: um documento num dos diretórios do catálogo do utilizador. Uma entidade resolvida a partir da cache não tem nenhum e nunca é fixada. Substitui o pin_sources_at_pull do espaço de trabalho nos dois sentidos: —pin-sources fixa nesta execução e —pin-sources=false para nesta execução, diga a definição o que disser |
--progress | false | Forçar a apresentação do progresso do pull mesmo quando o stderr não é um terminal, imprimindo uma linha simples por passo à medida que termina, com o respetivo tempo. A predefinição é auto: a lista de verificação interativa de fases só é mostrada quando o stderr é um terminal que interpreta sequências de escape, um terminal que não as interprete recebe as mesmas linhas simples, e uma saída redirecionada ou canalizada não recebe nenhuma |
--quiet | false | Silenciar a apresentação do progresso do pull no stderr. Não afeta o stdout. Tem precedência sobre —progress |
--release | — | Caminho para o ficheiro YAML da Release (obrigatório). Um caminho relativo é resolvido em relação ao diretório em que o comando é executado, não em relação à raiz do espaço de trabalho. Quando esse diretório não está em nenhum espaço de trabalho e nenhuma raiz é nomeada, um caminho absoluto encontra o espaço de trabalho a partir da própria pasta da Release |
--upgrade | false | Voltar a resolver as dependências a partir do estado atual do registo, fazendo flutuar cada uma para a versão mais alta disponível. Na forma simples (sem URIs posicionais) descarta o lockfile e volta a resolver todas as entidades, e pede confirmação primeiro porque elimina todas as fixações registadas; com um ou mais URIs de entidades, volta a resolver apenas esses, mantendo inalteradas todas as outras fixações e as entradas externas registadas, e não pergunta nada (mutuamente exclusivo com —verify) |
--verify | false | Verificar o lockfile existente em relação à resolução de dependências que um pull executaria agora, sem escrever o lockfile, o registo de confiança de plugins nem nenhum entity.lock; termina com código diferente de zero perante desvio ou lockfile em falta. A resolução respeita as fixações que o lockfile regista exatamente como um pull: uma referência cujo registo publicou uma versão mais recente desde o pull não é desvio, porque um pull manteria a sua fixação, e um registo que agora sirva bytes diferentes sob uma versão fixada faz parar a verificação tal como faz parar um pull. A cache de conteúdo é lida e preenchida como um pull a lê e preenche: uma entrada que a cache contém sob a sua fixação é lida daí sem perguntar a um registo, uma que não contém é obtida, e uma que já não corresponda à sua fixação é tratada exatamente como um pull a trata. Compara também o entity.lock junto de cada Recipe e FeatureRecipe dos diretórios do catálogo que a Release alcança com aquilo com que um build o compara, e termina com código diferente de zero perante uma fixação que um build recusaria: um ficheiro importado que já não corresponde ao seu digest registado, uma origem local cujos ficheiros já não correspondem aos seus digests registados, ou uma fixação de origem que discorda do lockfile. Compara ainda a assinatura que o lockfile regista para cada artefacto, e o registo de confiança de plugins para cada plugin, com a que um pull registaria agora, e termina com código diferente de zero onde um pull registaria, substituiria ou retiraria uma: uma assinatura que um requisito pede e que não está registada, e uma feita para outro artefacto, são reportadas sem perguntar a um registo, porque um pull reescreve-as seja qual for a resposta; uma assinatura que um pull volta a consultar e poderia registar sem alteração — o artefacto foi obtido, ou o seu pacote de assinatura em cache foi removido ou alterado — é perguntada no seu registo, ou, sob a postura offline, deixada por verificar com uma linha que o indica; e cada plugin que o registo de confiança de plugins abrange é verificado no seu registo, como todos os pulls o verificam, exceto sob a postura offline, onde é lido da cache de conteúdo como um build o lê, a sua identidade e as suas funções de anfitrião continuam a ser verificadas e a sua assinatura fica por verificar com uma linha que o indica, a menos que um build o recuse por não registar nenhuma ou por registar uma feita para outro artefacto, o que é reportado. Os marcadores de descontinuação não são comparados. Reporta também as versões do compilador e dos plugins principais que o lockfile regista — reportadas para auditoria e nunca comparadas com este binário, pelo que uma diferença de ferramentas nunca é desvio. Não é aceite com —pin-sources, seja qual for o valor dado: uma verificação não regista uma fixação que falte num entity.lock nem para perante ela, pelo que a opção não mudaria nada (mutuamente exclusivo com —upgrade) |
--yes | false | Responder antecipadamente à confirmação do —upgrade simples, para utilização não interativa. Abrange apenas essa pergunta e nada mais: todas as outras formas de pull não perguntam nada, pelo que passá-la não altera nenhum comportamento aí |