Schéma du verrou d’entité d’Aggrega
Référence générée. Ne pas modifier à la main — régénérer à partir du JSON Schema publié.
Identifiant du schéma : https://aggrega.ai/schemas/entity-lock-v1beta1.schema.json
Le fichier entity.lock qui se trouve à côté d’une entité et enregistre les épinglages de contenu des éléments que cette entité va chercher en dehors de son propre document : les fichiers qu’importent ses artefacts, les fichiers d’une source locale et les sources distantes dont l’entité écrit l’identité en entier — et, pour une source locale qui est un répertoire, les règles qui ont décidé lesquels de ses fichiers appartiennent à l’entité. Une seule étape l’écrit : aggrega pin, que l’auteur de l’entité exécute et qui ne nécessite aucune Release. aggrega pull et aggrega push exécutent cette même étape, et écrivent les mêmes octets, lorsqu’on le leur demande — avec --pin-sources, ou avec pin_sources_at_pull ou pin_sources_at_push de l’espace de travail. Un pull auquel on ne demande pas d’épingler n’écrit rien ici : sur une entité située dans les répertoires de catalogue propres à l’espace de travail, il compare ce que l’étape enregistrerait avec ce que contient le fichier, et s’interrompt, en nommant aggrega pin, là où un épinglage manque ou ne correspond plus à son élément — pour une source locale, un fichier ajouté, modifié ou supprimé depuis l’épinglage interrompt le pull comme tout autre épinglage périmé. aggrega build le relit et s’interrompt lorsque ce qui se trouve sur disque ne donne plus le digest enregistré. Sa portée est donnée par le répertoire dans lequel il se trouve — il épingle les éléments de l’entité de ce répertoire — de sorte qu’un seul nom de fichier sert à tous les types au lieu que chaque type porte sa propre graphie. L’étape supprime le verrou d’une entité qui ne lit aucun élément de ce genre, plutôt que d’en laisser un vide. Le document de l’entité lui-même n’est jamais écrit par la machine : ce qu’un auteur a saisi reste exactement tel qu’il l’a saisi, et ce que la machine a dérivé se trouve ici. C’est cette séparation qui rend le verrou sûr à committer et lisible sous forme de diff, car chaque ligne nomme un élément et un digest modifié nomme l’élément qui a changé. Il ne contient aucun horodatage ni aucune métadonnée de résolution, de sorte que réexécuter l’étape sur des éléments inchangés laisse le fichier identique octet pour octet. Une seule forme de ligne sert à tous les types qui peuvent enregistrer un épinglage, de sorte qu’un épinglage se lit de la même façon quel que soit le type auquel il appartient. La forme sérialisée est fermée (additionalProperties: false). Discipline d’évolution du schéma : ajouter un nouveau champ facultatif est SemVer-MINOR (additif) ; supprimer un champ ou resserrer une contrainte est SemVer-MAJOR.
Type de premier niveau : object
Propriétés
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
version | const 1 | oui | Version du schéma du verrou d’entité : 1. Une modification SemVer-MAJOR du schéma l’incrémente. Constante : 1 |
sourceDigests | object[] | non | Épinglages de contenu des sources distantes que cette entité référence et dont l’entité écrit l’identité en entier, figés lors de la résolution à partir des octets récupérés et relus au moment du build pour vérifier que la source en cache n’a pas dérivé. Chaque entrée reflète l’identité de la source résolue {kind, url, chart, moduleSubdir, version} plus le digest du contenu (et, pour une source distribuée par OCI, le digest du manifeste). Une source dont l’identité est renseignée à partir d’un template — une version lue dans les valeurs d’infrastructure d’une Release, par exemple — n’a aucune entrée ici : l’artefact qu’elle nomme est décidé par chaque Release qui utilise l’entité, de sorte que chaque identité vers laquelle elle se résout est épinglée à la place dans le fichier de verrouillage de cette Release. Une source locale (relative au système de fichiers) n’a pas non plus d’entrée ici : elle nomme un chemin plutôt que quelque chose de récupéré, de sorte qu’il n’existe aucune archive obtenue à épingler, et ses fichiers sont épinglés un par un dans localSourceDigests à la place. |
artifactDigests | object[] | non | Épinglages de contenu des fichiers qu’importent les artefacts de cette entité via $import — pour une Recipe, ceux qu’importent aussi ses entrées boundary.artifacts — figés lors de la résolution et relus au moment du build pour vérifier que le fichier importé n’a pas dérivé. Une entrée par artefact dont la valeur est une importation de fichier ; un artefact inline (littéral) fait déjà partie de l’entité et ne porte pas d’épinglage distinct, et un artefact tiré d’une bibliothèque est épinglé par la version à laquelle cette bibliothèque s’est résolue. Un build compare de la même façon une entrée de l’un ou l’autre bloc avec son épinglage, et refuse dans la même condition un fichier qui n’y correspond plus. |
localSourceDigests | object[] | non | Épinglages de contenu des fichiers de la source locale de cette entité — une source écrite comme un chemin à côté de l’entité plutôt que récupérée — figés lorsque l’entité est épinglée et relus au moment du build pour vérifier que les fichiers n’ont pas dérivé. Une entrée par fichier que la source apporte à ce que porte une publication de l’entité : chaque fichier sous le répertoire que nomme la source et que conservent les règles enregistrées sous ignore, ou l’unique fichier qu’elle nomme. Une source locale écrite comme un template ne nomme son répertoire qu’une fois qu’une Release a renseigné le template, de sorte qu’elle apporte chaque fichier du répertoire propre de l’entité que conservent les règles enregistrées, et chacun d’eux est épinglé. Le document de l’entité, le .aggregaignore de l’auteur à côté de lui et ce fichier ne sont jamais des entrées : le document est l’entité elle-même, les règles du fichier d’exclusion sont enregistrées sous ignore, et le verrou ne peut pas enregistrer son propre digest. Dès que le verrou enregistre une entrée ici, un build refuse une source qui contient un fichier sans entrée, un fichier dont le contenu ne donne plus le digest de son entrée, ou à laquelle manque un fichier que nomme une entrée. |
ignore | object | non | Les règles qui décident quels fichiers sous le répertoire de la source locale de cette entité lui appartiennent, enregistrées lorsque l’entité est épinglée. Toute lecture ultérieure de ce répertoire applique ces règles et rien d’autre : une publication de l’entité, la comparaison à laquelle un pull ou une publication soumet le verrou, la ligne d’entité de l’auteur, la comparaison d’un build et son rendu, et un pull de vérification. Ainsi, une modification du .aggregaignore de l’auteur, de la liaison du fournisseur de l’espace de travail ou du binaire aggrega ne déplace aucun digest tant que l’entité n’est pas épinglée de nouveau, et l’épingler de nouveau montre la modification ici sous forme de diff. Présent uniquement là où l’entité déclare une source locale qui est un répertoire, ou une source écrite comme un template. Un verrou qui n’enregistre aucune règle conserve chaque fichier sous ce répertoire. Un lien symbolique situé n’importe où en dessous est refusé plutôt que suivi. |
Les propriétés supplémentaires ne sont pas autorisées.
entity-lock.sourceDigests[]
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
kind | enum | oui | Le type de la source résolue. L’un d’un ensemble fermé — le même ensemble que portent le kind de l’artefact source du fichier de verrouillage et le kind des métadonnées du cache — car tous trois enregistrent les mêmes identités de sources résolues et un build lit le type pour choisir le chargeur. terraform-module-oci appartient à l’ensemble, et aucun adaptateur de source ne le sert : une Recipe ou une FeatureRecipe qui le nomme est refusée dès sa lecture. Valeurs autorisées : "helm-oci-chart", "helm-https-chart", "compose-https-fragment", "git-repository", "terraform-module-oci" |
url | string | oui | L’URL source rédigée qu’épingle le digest — l’URL d’identité telle qu’écrite dans spec.source.url (une racine de dépôt ou un .tgz direct pour helm-https-chart). Le build reconstruit cette même URL hors ligne, de sorte qu’elle est l’identité stable sur laquelle l’épinglage est indexé, et non un emplacement résolu de l’artefact. |
chart | string | non | Le nom du chart pour une source helm à racine de dépôt (spec.source.chart), partie de l’identité de la source résolue, de sorte que deux charts servis depuis une même racine de dépôt à la même version sont épinglés distinctement. Absent pour une source .tgz directe, OCI, compose ou git, dont aucune ne sélectionne un chart au sein de l’URL. |
moduleSubdir | string | non | Le répertoire, au sein d’un dépôt provenant de git, qui constitue l’artefact (spec.source.module_subdir), partie de l’identité de la source résolue, de sorte que deux répertoires d’un même dépôt au même commit sont épinglés distinctement. Absent lorsque le dépôt entier est l’artefact, et pour tout type qui atteint son artefact par URL plutôt qu’en descendant dans un clone. |
version | string | oui | La version concrète épinglée vers laquelle la source s’est résolue — une version de chart pour un type helm-*, le commit vers lequel une référence git-repository s’est résolue. Enregistrée sous la forme d’un seul segment de chemin, car elle construit l’emplacement du cache depuis lequel le build relit la source, de sorte qu’elle ne contient ni /, ni \, ni ... Motif : ^([^/\\.]|\.[^/\\.])*\.?$. |
digest | string | oui | Le digest du contenu de l’archive source récupérée, sous la forme sha256: suivi de 64 caractères hexadécimaux en minuscules, vérifié par rapport aux octets en cache au moment du build. Motif : ^sha256:[a-f0-9]{64}$. |
manifestDigest | string | non | Le digest du manifeste OCI pour une source distribuée par OCI — la racine de confiance indépendante — sous la forme sha256: suivi de 64 caractères hexadécimaux en minuscules. Présent uniquement pour une source OCI (un helm-oci-chart) ; absent pour une source https ou git, qui par construction ne porte aucun manifeste. Motif : ^sha256:[a-f0-9]{64}$. |
Les propriétés supplémentaires ne sont pas autorisées.
entity-lock.artifactDigests[]
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
name | string | oui | L’artefact dont cette entrée épingle le fichier $import : la clé de map artifacts: pour une entrée de artifacts, et boundary/ suivi de la clé pour une entrée de boundary.artifacts d’une Recipe — de sorte qu’une entrée de chaque bloc écrite sous une même clé est épinglée à part. |
digest | string | oui | Le digest du contenu des octets du fichier importé, sous la forme sha256: suivi de 64 caractères hexadécimaux en minuscules, vérifié au moment du build. Motif : ^sha256:[a-f0-9]{64}$. |
Les propriétés supplémentaires ne sont pas autorisées.
entity-lock.localSourceDigests[]
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
path | string | oui | Le chemin du fichier relatif au répertoire qui contient le document de l’entité, écrit avec des barres obliques — charts/app/templates/deployment.yaml, par exemple. |
digest | string | oui | Le digest du contenu des octets du fichier, sous la forme sha256: suivi de 64 caractères hexadécimaux en minuscules, vérifié au moment du build. Motif : ^sha256:[a-f0-9]{64}$. |
Les propriétés supplémentaires ne sont pas autorisées.
entity-lock.ignore
Les règles qui décident quels fichiers sous le répertoire de la source locale de cette entité lui appartiennent, enregistrées lorsque l’entité est épinglée. Toute lecture ultérieure de ce répertoire applique ces règles et rien d’autre : une publication de l’entité, la comparaison à laquelle un pull ou une publication soumet le verrou, la ligne d’entité de l’auteur, la comparaison d’un build et son rendu, et un pull de vérification. Ainsi, une modification du .aggregaignore de l’auteur, de la liaison du fournisseur de l’espace de travail ou du binaire aggrega ne déplace aucun digest tant que l’entité n’est pas épinglée de nouveau, et l’épingler de nouveau montre la modification ici sous forme de diff. Présent uniquement là où l’entité déclare une source locale qui est un répertoire, ou une source écrite comme un template. Un verrou qui n’enregistre aucune règle conserve chaque fichier sous ce répertoire. Un lien symbolique situé n’importe où en dessous est refusé plutôt que suivi.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
plugin | object | non | Le plugin qui servait la capacité de l’entité dans l’espace de travail de l’auteur lorsque l’entité a été épinglée — la liaison du fournisseur de l’espace de travail pour cette capacité, ou à défaut le plugin intégré au binaire aggrega — nommé sans version, et les règles d’exclusion qu’il a déclarées. Aucune version ni aucun digest du plugin n’est enregistré : les règles sont ce qu’applique chaque lecture, de sorte qu’épingler de nouveau sous une autre version du même plugin laisse le verrou inchangé, sauf si les règles ont changé. Un pull dont le propre plugin pour la capacité déclare des règles différentes le signale dans un avis, en nommant les deux plugins et la différence, et ne s’interrompt jamais pour cela. Absent là où aucun plugin ne servait la capacité. |
rules | object[] | non | Les règles exactes composées, dans l’ordre où elles s’appliquent : les motifs du plugin, puis les lignes de chaque fichier d’exclusion que nomme le plugin et que le parcours a trouvé, le fichier propre d’un répertoire avant ceux situés en dessous, puis les lignes du .aggregaignore de l’auteur à côté de l’entité. Une correspondance ultérieure l’emporte sur une précédente, de sorte que le fichier de l’auteur a le dernier mot sur tout chemin qu’il nomme, et une ligne commençant par ! rétablit ce qu’une règle précédente a exclu. Un répertoire qu’une règle exclut n’est pas parcouru, de sorte qu’un fichier qu’il contient ne revient qu’une fois que le répertoire revient. |
Les propriétés supplémentaires ne sont pas autorisées.
entity-lock.ignore.plugin
Le plugin qui servait la capacité de l’entité dans l’espace de travail de l’auteur lorsque l’entité a été épinglée — la liaison du fournisseur de l’espace de travail pour cette capacité, ou à défaut le plugin intégré au binaire aggrega — nommé sans version, et les règles d’exclusion qu’il a déclarées. Aucune version ni aucun digest du plugin n’est enregistré : les règles sont ce qu’applique chaque lecture, de sorte qu’épingler de nouveau sous une autre version du même plugin laisse le verrou inchangé, sauf si les règles ont changé. Un pull dont le propre plugin pour la capacité déclare des règles différentes le signale dans un avis, en nommant les deux plugins et la différence, et ne s’interrompt jamais pour cela. Absent là où aucun plugin ne servait la capacité.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
name | string | oui | Le plugin qui servait la capacité de l’entité lorsqu’elle a été épinglée, sous la forme <pluginType>/<name>, sans version : les règles ci-dessous sont ce qu’applique une lecture, et le nom dit à qui elles appartenaient. Au moins 1 caractère. |
patterns | string[] | non | Les motifs d’exclusion que le plugin a déclarés, tels qu’il les a déclarés. |
files | string[] | non | Les noms des fichiers d’exclusion dont le plugin a déclaré que son écosystème les respecte au sein d’une source. |
Les propriétés supplémentaires ne sont pas autorisées.
entity-lock.ignore.rules[]
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
pattern | string | oui | Un motif d’exclusion dans la syntaxe gitignore. |
within | string | oui | Le répertoire auquel s’étend la portée du motif, relatif au répertoire qui contient le document de l’entité et écrit avec des barres obliques ; . nomme ce répertoire lui-même. Un motif que déclare le plugin a pour portée le répertoire de la source locale, une ligne d’un fichier d’exclusion le répertoire qui contient ce fichier, et une ligne du .aggregaignore de l’auteur le répertoire de l’entité. |
from | string | oui | Où le motif a été déclaré : plugin pour un motif déclaré par le plugin, et sinon le chemin du fichier d’exclusion dont il a été lu, relatif au répertoire qui contient le document de l’entité. |
Les propriétés supplémentaires ne sont pas autorisées.