Esquema do bloqueio de entidade do Aggrega
Referência gerada. Não editar à mão — gerar novamente a partir do JSON Schema publicado.
ID do esquema: https://aggrega.ai/schemas/entity-lock-v1beta1.schema.json
O ficheiro entity.lock que se encontra junto a uma entidade e regista as fixações de conteúdo dos elementos que essa entidade vai buscar fora do seu próprio documento: os ficheiros que os seus artefactos importam, os ficheiros de uma fonte local e as fontes remotas cuja identidade a entidade escreve por extenso — e, para uma fonte local que é um diretório, as regras que decidiram quais dos seus ficheiros pertencem à entidade. Um único passo escreve-o: aggrega pin, que o autor da entidade executa e que não precisa de nenhuma Release. aggrega pull e aggrega push executam esse mesmo passo, e escrevem os mesmos bytes, quando tal lhes é pedido — com --pin-sources, ou com pin_sources_at_pull ou pin_sources_at_push do espaço de trabalho. Um pull ao qual não é pedido que fixe não escreve nada aqui: sobre uma entidade nos diretórios de catálogo do próprio espaço de trabalho, compara aquilo que o passo registaria com aquilo que o ficheiro contém, e é interrompido, nomeando aggrega pin, onde uma fixação está em falta ou já não corresponde ao seu elemento — para uma fonte local, um ficheiro acrescentado, alterado ou removido desde a fixação interrompe o pull como qualquer outra fixação desatualizada. aggrega build volta a lê-lo e é interrompido quando aquilo que está em disco já não produz o digest registado. O seu âmbito é dado pelo diretório em que se encontra — fixa os elementos da entidade nesse diretório — pelo que um único nome de ficheiro serve todos os tipos, em vez de cada tipo ter uma grafia própria. O passo remove o bloqueio de uma entidade que não lê nenhum elemento assim, em vez de deixar um vazio. O próprio documento da entidade nunca é escrito pela máquina: aquilo que um autor escreveu fica exatamente como foi escrito, e aquilo que a máquina derivou fica aqui. É esta separação que torna o bloqueio seguro para commit e legível como diff, porque cada linha nomeia um elemento e um digest alterado nomeia o elemento que mudou. Não tem nenhum carimbo temporal nem metadados de resolução, pelo que voltar a executar o passo sobre elementos inalterados deixa o ficheiro idêntico byte a byte. Uma única forma de linha serve todos os tipos que podem registar uma fixação, pelo que uma fixação se lê da mesma forma, seja qual for o tipo a que pertence. A forma serializada é fechada (additionalProperties: false). Disciplina de evolução do esquema: acrescentar um novo campo opcional é SemVer-MINOR (aditivo); remover um campo ou tornar uma restrição mais rígida é SemVer-MAJOR.
Tipo de nível superior: object
Propriedades
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
version | const 1 | sim | Versão do esquema do bloqueio de entidade: 1. Uma alteração SemVer-MAJOR ao esquema incrementa-a. Constante: 1 |
sourceDigests | object[] | não | Fixações de conteúdo das fontes remotas que esta entidade referencia e cuja identidade a entidade escreve por extenso, congeladas na resolução a partir dos bytes obtidos e relidas na compilação para verificar que a fonte em cache não se desviou. Cada entrada espelha a identidade da fonte resolvida {kind, url, chart, moduleSubdir, version} mais o digest de conteúdo (e, para uma fonte distribuída via OCI, o digest do manifesto). Uma fonte cuja identidade é preenchida a partir de um template — uma versão lida dos valores de infraestrutura de uma Release, por exemplo — não tem nenhuma entrada aqui: o artefacto que nomeia é decidido por cada Release que usa a entidade, pelo que cada identidade para a qual é resolvida é fixada, em vez disso, no ficheiro de bloqueio dessa Release. Uma fonte local (relativa ao sistema de ficheiros) também não tem entrada aqui: nomeia um caminho em vez de algo obtido, pelo que não há nenhum arquivo adquirido a fixar, e os seus ficheiros são fixados um a um em localSourceDigests em vez disso. |
artifactDigests | object[] | não | Fixações de conteúdo dos ficheiros que os artefactos desta entidade importam através de $import — para uma Recipe, também os que as suas entradas de boundary.artifacts importam — congeladas na resolução e relidas na compilação para verificar que o ficheiro importado não se desviou. Uma entrada por artefacto cujo valor é uma importação de ficheiro; um artefacto inline (literal) já faz parte da entidade e não tem uma fixação separada, e um artefacto obtido de uma biblioteca é fixado pela versão para a qual essa biblioteca foi resolvida. Uma compilação compara da mesma forma uma entrada de qualquer um dos dois blocos com a sua fixação, e recusa na mesma condição um ficheiro que já não lhe corresponde. |
localSourceDigests | object[] | não | Fixações de conteúdo dos ficheiros da fonte local desta entidade — uma fonte escrita como um caminho junto à entidade em vez de obtida — congeladas quando a entidade é fixada e relidas na compilação para verificar que os ficheiros não se desviaram. Uma entrada por cada ficheiro com que a fonte contribui para aquilo que uma publicação da entidade contém: cada ficheiro sob o diretório que a fonte nomeia que as regras registadas em ignore mantêm, ou o único ficheiro que nomeia. Uma fonte local escrita como template só nomeia o seu diretório quando uma Release preenche o template, pelo que contribui com cada ficheiro do próprio diretório da entidade que as regras registadas mantêm, e cada um deles é fixado. O documento da entidade, o .aggregaignore do autor junto a ele e este ficheiro nunca são entradas: o documento é a própria entidade, as regras do ficheiro de exclusão são registadas em ignore e o bloqueio não pode registar o seu próprio digest. Assim que o bloqueio regista alguma entrada aqui, uma compilação recusa uma fonte que contenha um ficheiro sem entrada, um ficheiro cujo conteúdo já não produz o digest da sua entrada, ou à qual falte um ficheiro que uma entrada nomeia. |
ignore | objeto | não | As regras que decidem que ficheiros sob o diretório da fonte local desta entidade lhe pertencem, registadas quando a entidade é fixada. Cada leitura posterior desse diretório aplica estas regras e nada mais: uma publicação da entidade, a comparação a que um pull ou uma publicação sujeita o bloqueio, a linha de entidade do autor, a comparação de uma compilação e a sua renderização, e um pull de verificação. Assim, uma alteração ao .aggregaignore do autor, à associação do fornecedor do espaço de trabalho ou ao binário aggrega não move nenhum digest até a entidade ser fixada de novo, e fixá-la de novo mostra aqui a alteração como um diff. Presente apenas onde a entidade declara uma fonte local que é um diretório, ou uma escrita como template. Um bloqueio que não regista regras mantém todos os ficheiros sob esse diretório. Uma ligação simbólica em qualquer ponto abaixo dele é recusada em vez de seguida. |
Não são permitidas propriedades adicionais.
entity-lock.sourceDigests[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
kind | enum | sim | O tipo da fonte resolvida. Um de um conjunto fechado — o mesmo conjunto que o kind do artefacto de fonte do ficheiro de bloqueio e o kind dos metadados da cache contêm — porque os três registam as mesmas identidades de fontes resolvidas e uma compilação lê o tipo para escolher o carregador. terraform-module-oci pertence ao conjunto, e nenhum adaptador de fonte o serve: uma Recipe ou uma FeatureRecipe que o nomeie é recusada assim que é lida. Valores permitidos: "helm-oci-chart", "helm-https-chart", "compose-https-fragment", "git-repository", "terraform-module-oci" |
url | string | sim | O URL da fonte escrito pelo autor que o digest fixa — o URL de identidade tal como está escrito em spec.source.url (uma raiz de repositório ou um .tgz direto para helm-https-chart). A compilação reconstrói esse mesmo URL offline, pelo que é a identidade estável pela qual a fixação é indexada, e não uma localização resolvida do artefacto. |
chart | string | não | O nome do chart para uma fonte helm de raiz do repositório (spec.source.chart), parte da identidade da fonte resolvida, pelo que dois charts servidos a partir de uma mesma raiz de repositório na mesma versão são fixados separadamente. Ausente para uma fonte .tgz direta, OCI, compose ou git, nenhuma das quais seleciona um chart dentro do URL. |
moduleSubdir | string | não | O diretório dentro de um repositório obtido via git que é o artefacto (spec.source.module_subdir), parte da identidade da fonte resolvida, pelo que dois diretórios de um mesmo repositório no mesmo commit são fixados separadamente. Ausente quando o repositório inteiro é o artefacto, e para todos os tipos que chegam ao seu artefacto por URL em vez de descerem num clone. |
version | string | sim | A versão concreta fixada para a qual a fonte foi resolvida — uma versão de chart para um tipo helm-*, o commit para o qual uma referência git-repository foi resolvida. Registada como um único segmento de caminho, porque forma o slot da cache a partir do qual a compilação relê a fonte, pelo que não contém /, nem \, nem ... Padrão: ^([^/\\.]|\.[^/\\.])*\.?$. |
digest | string | sim | O digest de conteúdo do arquivo da fonte obtido, na forma sha256: seguido de 64 caracteres hexadecimais minúsculos, verificado face aos bytes em cache na compilação. Padrão: ^sha256:[a-f0-9]{64}$. |
manifestDigest | string | não | O digest do manifesto OCI para uma fonte distribuída via OCI — a raiz de confiança independente — na forma sha256: seguido de 64 caracteres hexadecimais minúsculos. Presente apenas para uma fonte OCI (um helm-oci-chart); ausente para uma fonte https ou git, que por construção não tem nenhum manifesto. Padrão: ^sha256:[a-f0-9]{64}$. |
Não são permitidas propriedades adicionais.
entity-lock.artifactDigests[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | O artefacto cujo ficheiro $import esta entrada fixa: a chave do mapa artifacts: para uma entrada de artifacts, e boundary/ seguido da chave para uma entrada de boundary.artifacts de uma Recipe — pelo que uma entrada de cada bloco escrita sob uma mesma chave é fixada separadamente. |
digest | string | sim | O digest de conteúdo dos bytes do ficheiro importado, na forma sha256: seguido de 64 caracteres hexadecimais minúsculos, verificado na compilação. Padrão: ^sha256:[a-f0-9]{64}$. |
Não são permitidas propriedades adicionais.
entity-lock.localSourceDigests[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
path | string | sim | O caminho do ficheiro relativo ao diretório que contém o documento da entidade, escrito com barras normais — charts/app/templates/deployment.yaml, por exemplo. |
digest | string | sim | O digest de conteúdo dos bytes do ficheiro, na forma sha256: seguido de 64 caracteres hexadecimais minúsculos, verificado na compilação. Padrão: ^sha256:[a-f0-9]{64}$. |
Não são permitidas propriedades adicionais.
entity-lock.ignore
As regras que decidem que ficheiros sob o diretório da fonte local desta entidade lhe pertencem, registadas quando a entidade é fixada. Cada leitura posterior desse diretório aplica estas regras e nada mais: uma publicação da entidade, a comparação a que um pull ou uma publicação sujeita o bloqueio, a linha de entidade do autor, a comparação de uma compilação e a sua renderização, e um pull de verificação. Assim, uma alteração ao .aggregaignore do autor, à associação do fornecedor do espaço de trabalho ou ao binário aggrega não move nenhum digest até a entidade ser fixada de novo, e fixá-la de novo mostra aqui a alteração como um diff. Presente apenas onde a entidade declara uma fonte local que é um diretório, ou uma escrita como template. Um bloqueio que não regista regras mantém todos os ficheiros sob esse diretório. Uma ligação simbólica em qualquer ponto abaixo dele é recusada em vez de seguida.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
plugin | objeto | não | O plugin que servia a capacidade da entidade no espaço de trabalho do autor quando a entidade foi fixada — a associação do fornecedor do espaço de trabalho para essa capacidade, ou, caso contrário, o plugin incorporado no binário aggrega — nomeado sem versão, e as regras de exclusão que declarou. Não é registada nenhuma versão nem nenhum digest do plugin: as regras são aquilo que cada leitura aplica, pelo que fixar de novo com outra versão do mesmo plugin deixa o bloqueio inalterado, a menos que as regras tenham mudado. Um pull cujo próprio plugin para a capacidade declara regras diferentes indica-o num aviso, nomeando ambos os plugins e a diferença, e nunca é interrompido por isso. Ausente onde nenhum plugin servia a capacidade. |
rules | object[] | não | As regras exatas compostas, pela ordem em que se aplicam: os padrões do plugin, depois as linhas de cada ficheiro de exclusão que o plugin nomeia e que o percurso encontrou, o ficheiro próprio de um diretório antes dos que estão abaixo dele, depois as linhas do .aggregaignore do autor junto à entidade. Uma correspondência posterior prevalece sobre uma anterior, pelo que o ficheiro do autor tem a última palavra sobre qualquer caminho que nomeie, e uma linha que comece por ! repõe aquilo que uma regra anterior excluiu. Um diretório que uma regra exclui não é percorrido, pelo que um ficheiro sob ele só volta quando o diretório volta. |
Não são permitidas propriedades adicionais.
entity-lock.ignore.plugin
O plugin que servia a capacidade da entidade no espaço de trabalho do autor quando a entidade foi fixada — a associação do fornecedor do espaço de trabalho para essa capacidade, ou, caso contrário, o plugin incorporado no binário aggrega — nomeado sem versão, e as regras de exclusão que declarou. Não é registada nenhuma versão nem nenhum digest do plugin: as regras são aquilo que cada leitura aplica, pelo que fixar de novo com outra versão do mesmo plugin deixa o bloqueio inalterado, a menos que as regras tenham mudado. Um pull cujo próprio plugin para a capacidade declara regras diferentes indica-o num aviso, nomeando ambos os plugins e a diferença, e nunca é interrompido por isso. Ausente onde nenhum plugin servia a capacidade.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | O plugin que servia a capacidade da entidade quando foi fixada, como <pluginType>/<name>, sem versão: as regras abaixo são aquilo que uma leitura aplica, e o nome diz a quem pertenciam. Pelo menos 1 carácter de comprimento. |
patterns | string[] | não | Os padrões de exclusão que o plugin declarou, tal como os declarou. |
files | string[] | não | Os nomes dos ficheiros de exclusão que o plugin declarou que o seu ecossistema respeita dentro de uma fonte. |
Não são permitidas propriedades adicionais.
entity-lock.ignore.rules[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
pattern | string | sim | Um padrão de exclusão na sintaxe gitignore. |
within | string | sim | O diretório a que o âmbito do padrão se limita, relativo ao diretório que contém o documento da entidade e escrito com barras normais; . nomeia esse próprio diretório. Um padrão que o plugin declara tem como âmbito o diretório da fonte local, uma linha de um ficheiro de exclusão o diretório que contém esse ficheiro, e uma linha do .aggregaignore do autor o diretório da entidade. |
from | string | sim | Onde o padrão foi declarado: plugin para um que o plugin declarou e, caso contrário, o caminho do ficheiro de exclusão a partir do qual foi lido, relativo ao diretório que contém o documento da entidade. |
Não são permitidas propriedades adicionais.