aggrega pull
aggrega pull résout toutes les dépendances d’une Release et écrit un lockfile qui épingle chaque dépendance à une version et à un digest de contenu exacts. Un aggrega build ultérieur utilise ce qu’épingle le lockfile, le vérifie et s’arrête en nommant tout ce dont il a besoin et qui n’y est pas épinglé — les builds sont ainsi reproductibles et utilisables hors ligne.
Tout ce qu’une build consomme est épinglé à ce seul moment. Les entités du catalogue, les artefacts sources vers lesquels une Recipe dirige un provider et les documents distants qu’un provider demande pendant son rendu sont résolus par la même commande et enregistrés dans la même écriture du lockfile. aggrega pull est l’étape qui touche le réseau ; la build, non. C’est là toute la règle, et le reste de cette page en découle.
Fonctionnement
aggrega pull résout trois types de dépendances en une seule passe :
- Entités du catalogue — les Components, Features, Recipes, FeatureRecipes, bibliothèques de schémas et de mappings et plugins Wasm que la Release référence, résolus de manière transitive (via
extends:,implements:,aggregate:, les rattachements de Feature et les sites$import:/$ref:des bibliothèques) et récupérés depuis le registre lorsqu’ils ne sont pas déjà présents localement. - Artefacts source — la
source:distante vers laquelle une Recipe ou une FeatureRecipe donnée oriente un provider : un chart Helm (OCI ou HTTPS classique) ou un fragment Compose sur HTTPS. Chacun est récupéré, mis en cache et épinglé. - Entrées externes — les documents distants qu’un provider demande à l’hôte pendant son rendu, comme un
$refdans levalues.schema.jsond’un chart qui pointe vers une URL. Chacune est récupérée, stockée sous son digest de contenu et épinglée.
Deux des trois sont lus dans les documents que vous avez rédigés. Le troisième non : les entrées externes sont trouvées en effectuant le rendu de la Release, et c’est pourquoi cette commande en effectue un. Exécuter la commande ne nécessite rien de tout cela — Comment la résolution trouve les entrées externes l’explique en détail, ainsi que ce que coûte le rendu, ce qui se passe lorsqu’il ne peut pas aboutir et la façon dont un build qui remplit son propre lockfile s’y rapporte.
Une entité de catalogue nommée sans registre est récupérée via le default_registry de l’espace de travail, et un chemin de dépôt que contient cette valeur par défaut est l’endroit d’où elle est récupérée. Avec default_registry: ghcr.io/acme, core/api-server est récupéré depuis ghcr.io/acme/component/core/api-server — là où aggrega push le publie via la même valeur par défaut — et c’est là que sa signature est recherchée. Le chemin n’indique que l’emplacement : la signature qu’exige un pull, les clés et identités auxquelles il fait confiance et l’identifiant qu’il présente sont ceux conservés pour l’hôte, de sorte que l’entrée registries pour ghcr.io régit chaque chemin sur cet hôte. Le lockfile enregistre une telle entité par son identité, sa version et ses digests, comme il enregistre une entité récupérée depuis un hôte seul. La syntaxe d’un chemin est décrite dans comment s’écrit un hôte de registre.
La commande écrit le résultat dans <release-stem>.lock à côté de la Release. Un espace de travail qui rattache un plugin renvoyant un verdict d’acceptation ou de rejet obtient aussi un second fichier dans ce répertoire — l’enregistrement de confiance des plugins.
Un pull à qui l’on demande d’épingler écrit un type de fichier supplémentaire. À côté de chaque Recipe et FeatureRecipe de vos répertoires de catalogue qui importe un fichier d’artefact, pointe vers une source: distante que vous avez écrite en entier ou lit une source: située à côté d’elle se trouve un entity.lock qui enregistre le digest de ce contenu. L’enregistrer est l’étape de l’auteur de l’entité, aggrega pin, et par défaut un pull ne l’effectue pas : il confronte le lock de chacune de ces entités à ce que l’étape enregistrerait, et s’arrête là où un épinglage manque. aggrega pull --pin-sources, ou un espace de travail qui définit pin_sources_at_pull: true, exécute l’étape à la place — et l’effet d’un pull s’étend alors au-delà du répertoire où se trouve la Release, bien que les fichiers d’entité que vous avez rédigés ne soient jamais modifiés. Le lock d’entité décrit ce fichier, et Prévisualiser ce qu’un pull écrirait montre l’ensemble complet pour votre espace de travail avant que quoi que ce soit ne bouge.
Un pull refusé parce qu’une référence ne s’est résolue en rien indique d’où les entités locales sont lues, où qu’il s’exécute. Le refus porte le compte rendu propre de l’espace de travail sur les répertoires d’où il a lu les entités locales et sur ce qu’il faut changer pour que l’entité soit lue — la note que montre D’où les entités locales sont lues — et il le porte depuis cette commande, depuis un build qui résout d’abord ses dépendances, depuis l’outil de pull d’aggrega mcp et tout autant depuis la résolution des dépendances d’un éditeur, parce que c’est la résolution qu’ils exécutent tous qui le compose. Le refus de l’outil de pull nomme aussi le code court et le code descriptif de la condition, de même qu’un terminal affiche le code court en tête du refus. Un fichier de ces répertoires qui déclare une apiVersion Aggrega — une ligne commençant, sans indentation, par apiVersion: suivi d’une valeur commençant par aggrega.ai/ — et qui n’a pas pu être chargé, par exemple un fichier qui ne s’analyse pas comme du YAML, est nommé dans le même refus, parmi les fichiers de catalogue ignorés au chargement, avec la raison donnée par l’analyseur lui-même : un tel fichier peut être celui qui déclare l’entité que nomme la référence, et rien ne peut y être lu pour dire quelle entité il déclare. Un fichier YAML qui déclare une autre apiVersion, ou aucune, n’est pas un document Aggrega et n’y est jamais nommé.
Le lockfile
Le lockfile épingle chaque dépendance à son URI, à sa version résolue et à son digest de contenu. Il comporte des sections pour les entités du catalogue, les bibliothèques de schémas et de mappings (chacune portant des pointeurs inverses vers les Components et les Features qui la consomment), les plugins Wasm, les artefacts source, les entrées externes (chacune indexée par URL et portant les plugins qui l’ont demandée) et les fichiers de la Release eux-mêmes. Le fichier est écrit sous une forme canonique et déterministe.
Une entité est enregistrée d’après ce que contient une publication de celle-ci. Le digest de la ligne d’une entité couvre son document et chaque fichier qu’elle nomme à côté d’elle — la source: locale d’une Recipe ou d’une FeatureRecipe, chaque fichier que nomme un $import:, l’entity.lock à côté d’elle, chaque fichier de schéma qu’un Component ou une Feature importe — le même ensemble que publie aggrega push. Chaque fichier apporte son chemin et ses octets, et rien d’autre n’y contribue : ni la manière dont une archive a été compressée, ni un horodatage, ni un bit de permission, bit d’exécution compris. Une entité qui ne nomme aucun fichier est enregistrée comme ce seul document. Ainsi, la même entité enregistre le même digest qu’elle ait été lue depuis votre répertoire de catalogue ou récupérée depuis un registre, et un lockfile commité depuis un checkout se vérifie sur un autre checkout du même commit quel que soit son umask, et que le système de ce checkout enregistre ou non quels fichiers sont exécutables. Un chart modifié sous une Recipe, un fichier ajouté à une source qu’elle déclare et un entity.lock modifié changent chacun le digest ; un script dont le bit d’exécution a basculé, et une note à côté de l’entité que rien ne nomme, ne le changent pas. L’Aggregate et le Manifest que nomme la Release sont enregistrés de la même manière, chacun comme son unique document. Une bibliothèque est enregistrée par le digest de ses octets, qui sont son document où qu’elle soit lue.
Chaque Recipe et FeatureRecipe que le Manifest lie est une ligne, quel que soit le niveau qui la lie. Une réalisation que le niveau name du Manifest choisit pour une seule instance ou un seul rattachement est acquise et enregistrée exactement comme une réalisation que son niveau type choisit pour chaque instance d’un type, et le champ referenced_from de sa ligne nomme l’entrée qui la lie — manifest.spec.mappings.components.name.<instance> ou manifest.spec.mappings.features.name.<attachment>. Un build la confronte à cette ligne, de sorte qu’un lockfile qui ne l’enregistre pas arrête le build, en nommant la réalisation et cette entrée. Voir Mappage d’URI plat pour les deux niveaux.
Les rattachements d’une connexion sont des dépendances exactement comme ceux d’un composant. La Feature que nomme un rattachement sur une connexion — écrit sur une entrée uses: d’un composant dans l’Aggregate, ou sur une entrée de connexion dans la Release — est acquise et enregistrée comme la Feature d’un rattachement écrit sur le composant lui-même, et le champ referenced_from de sa ligne nomme l’entrée de connexion écrite par l’auteur, se terminant par .uses.<socket>.<alias>.features.<slot>.type. La réalisation que le Manifest lui lie est aussi une ligne, que ce soit features.type qui la lie ou features.name indexé par le nom du rattachement, <alias>.<slot>. Un build confronte les deux à leurs lignes : un lockfile sans l’une d’elles arrête le build en nommant la référence et l’entrée qui la demande, et une Feature dont le contenu a changé depuis le pull l’arrête en nommant les deux digests. Voir l’entrée de connexion de l’Aggregate pour le rattachement lui-même.
Une base qu’étend un Component ou une Feature constitue une ligne, que quelque chose d’autre la nomme ou non. Le pull suit chaque extends: jusqu’au bout de sa chaîne et enregistre chaque base sous son propre type d’entité, le referenced_from de sa ligne nommant le spec.extends de l’entité qui l’étend — component(<name>:<version>).spec.extends. Un build lit la base depuis cette ligne, de sorte qu’un Manifest mappe le type propre d’un wrapper et n’a besoin d’aucune ligne pour sa base. Une base qu’aucun répertoire de catalogue, aucun cache ni aucun registry ne détient est signalée là où la chaîne est fusionnée — voir An extends: chain cannot be assembled (Une chaîne ne peut pas être assemblée).
La Release est enregistrée d’après son contenu, pas seulement d’après son nom. Tout ce que demande la Release — vers quelle version de chart une source se résout, quels composants aboutissent dans quelle frontière — est résolu à partir de ce que contient le fichier, de sorte que release_documents enregistre le digest de la Release et de chaque Release qu’elle étend, à côté de release, qui la nomme. Modifiez la Release après le pull et le build suivant s’arrête avant tout rendu, en nommant le fichier modifié et en vous indiquant de refaire un pull ; un simple aggrega pull --release <release> enregistre la modification tout en respectant chaque autre épinglage. Le digest couvre les octets du fichier tels qu’ils sont, donc une modification d’un commentaire ou d’espaces compte aussi, exactement comme pour l’Aggregate et le Manifest. Un fichier que la Release importe via parameters n’est pas enregistré ainsi.
Un pull recherche un marqueur de dépréciation sur chaque artefact dont il vérifie la signature, et indique ce qu’il a trouvé. Un marqueur dont la propre signature se vérifie auprès d’un signataire que le pull reconnaît — le signataire de l’artefact lui-même, ou une identité figurant dans trusted_deprecation_identities du registre — est enregistré, et annoncé avec sa gravité et le signataire du marqueur. Un marqueur que le pull a trouvé et n’a pas pu reconnaître — illisible, non signé, signé par quelqu’un auquel la politique ne fait pas confiance, ou portant une signature qui n’a pas pu être vérifiée — est signalé comme marker present but not honored, avec la raison, et n’est pas enregistré. Une recherche qui n’a pas pu aboutir — le pull n’a pas pu ouvrir le registre de l’artefact, ou la liste de ce qui lui est attaché n’a pas répondu — est signalée comme marker lookup did not complete, avec la raison, et n’enregistre rien, parce que le pull n’a rien appris sur l’existence d’un marqueur. Sous un registre dont la propre politique de confiance exige une signature pour le type de l’artefact et n’est pas advisory, l’un ou l’autre de ces deux cas arrête le pull au lieu d’être signalé. Un artefact ne portant aucun marqueur ne produit aucune ligne, et lorsque la vérification des signatures est désactivée, pour l’espace de travail ou pour le registre de l’artefact, aucun marqueur n’est recherché.
Commitez <release-stem>.lock avec la Release, comme vous commitez tout manifeste de dépendances épinglées. Un diff du lockfile montre aux relecteurs exactement quelles versions et quels digests de dépendances ont changé ; un changement de digest d’une bibliothèque nomme les consommateurs qu’il affecte.
Ce qu’un pull donné a fait — si chaque entité a été récupérée à neuf depuis un registre (fetched-fresh), a réutilisé un emplacement du cache (cache-reuse), a été trouvée dans un catalogue local (local), a été servie depuis la copie intégrée au binaire du compilateur (in-binary) ou était externe (external : l’Aggregate ou le Manifest propre à la Release, lu depuis le fichier ou l’entrée que nomme la Release plutôt que résolu comme l’une de ses dépendances ; un Aggregate que le pull a récupéré depuis un registre est fetched-fresh à la place) — est un diagnostic transitoire d’événement de pull affiché sur stdout par --detail, et il n’est jamais écrit dans le lockfile. La source qui a servi une entité dépend de l’état local de la machine qui effectue le pull, donc la persister romprait l’identité octet par octet du lockfile d’une machine à l’autre. Il indique ce que ce pull a fait, ce qui est irrécupérable ensuite (une entité fraîchement récupérée est mise en cache par l’exécution suivante) ; pour l’état de résolution après pull des dépendances d’une Release, utilisez aggrega inspect.
Le lock d’entité
Une Recipe ou une FeatureRecipe peut dépendre d’octets extérieurs à son propre document : un chart ou un fragment récupéré depuis une source: distante, un fichier qu’une entrée artifacts — ou une entrée du boundary.artifacts d’une Recipe — apporte avec $import, ou les fichiers d’une source: qui nomme un répertoire ou un fichier à côté d’elle. Le digest de chacun d’eux est enregistré dans un fichier nommé entity.lock, dans le même répertoire que le fichier de l’entité. Le fichier d’entité que vous avez écrit n’est jamais modifié ; ce qui en a été dérivé vit à côté. Le schéma du lock d’entité décrit le fichier champ par champ.
Qui l’écrit. Une seule étape l’écrit : aggrega pin, que l’auteur de l’entité exécute, qui ne nécessite aucune Release et qui enregistre chaque classe d’épinglage que contient le lock. aggrega pull --pin-sources et aggrega push --pin-sources exécutent cette même étape pour le compte de l’auteur et écrivent les mêmes octets. Un pull à qui l’on n’a pas demandé d’épingler n’écrit aucun lock : pour chaque Recipe et FeatureRecipe que la Release construit à partir de vos répertoires de catalogue, il compare ce que l’étape enregistrerait avec ce que contient le lock, et s’arrête là où un épinglage manque ou ne correspond plus à son entrée, en nommant l’entité, chaque entrée et sa classe, ainsi que aggrega pin. Les fichiers d’une source locale sont confrontés à leurs épinglages comme un seul ensemble : un lock qui n’en enregistre aucun arrête le pull, tout comme un fichier ajouté, modifié ou supprimé depuis l’épinglage. La clé d’espace de travail pin_sources_at_pull fait de l’épinglage le comportement par défaut de chaque pull, et --pin-sources=false rétablit l’arrêt pour une exécution. L’épinglage est un devoir de l’auteur, donc un arrêt au premier pull d’un consommateur signifie que l’éditeur de l’entité ne l’a jamais épinglée ; le remède du consommateur est cette clé plutôt qu’une modification manuelle du répertoire de quelqu’un d’autre. aggrega pin l’expose en détail.
Ce qu’il contient. Trois listes, dont chaque ligne nomme une entrée :
sourceDigests— une ligne pour chaquesource:distante dont vous avez écrit les coordonnées en entier, sans modèle danskind,url,chart,module_subdir,versionouref. La ligne porte lekindet l’urlde la source, sonchartou sonmodule_subdirlorsqu’elle en a un, la version vers laquelle elle s’est résolue — pour une source git, le commit que nommait sonref— et le digest de contenu de l’archive récupérée, plus le digest du manifeste pour un chart récupéré via OCI.artifactDigests— une ligne pour chaque entréeartifactsouboundary.artifactsfournie par un fichier importé avec$import, nommant l’entrée et le digest des octets du fichier. Une entréeartifactsest nommée par sa clé, et une entréeboundary.artifactssous la formeboundary/<key>, de sorte qu’une entrée de chaque bloc écrite sous une même clé est épinglée séparément.localSourceDigests— une ligne pour chaque fichier qu’unesource:nommant un répertoire ou un fichier à côté de l’entité apporte à ce que contient une publication de l’entité, nommant le chemin du fichier à côté de l’entité et le digest de ses octets. Rien n’est récupéré pour une telle source ; le digest de ses fichiers est calculé tels qu’ils sont. Une source écrite sous forme de modèle apporte chaque fichier du répertoire de l’entité, donc chacun d’eux a une ligne.
Ce qu’il ne contient pas :
- Une source distante dont les coordonnées sont renseignées à partir d’un modèle — une
versionlue depuis.infra, par exemple. L’artefact qu’elle nomme est décidé par chaque Release qui utilise l’entité, donc chaque version vers laquelle elle se résout est épinglée dans le lockfile de cette Release, et rien la concernant n’est écrit à côté de l’entité. - Une entrée
artifactsouboundary.artifactsen ligne, qui fait partie du fichier de l’entité, et une entrée tirée d’une ArtifactLibrary, dont le contenu est épinglé par la version de bibliothèque qu’enregistre le lockfile.
Une entité sans rien à épingler n’obtient aucun entity.lock, et l’étape, exécutée sur une entité qui n’en a plus besoin, le supprime.
Commitez-le à côté de l’entité. Chaque Recipe et FeatureRecipe utilise le même nom de fichier, et le répertoire où il se trouve indique à quelle entité il appartient, de sorte que le lock voyage avec ce répertoire. Il ne contient aucun horodatage et ses lignes sont conservées dans un ordre fixe, de sorte que l’étape exécutée sur des entrées inchangées le laisse identique octet pour octet, et qu’un diff sur ce fichier nomme la source, le fichier importé ou le fichier de la source locale qui a bougé. Un répertoire contient un seul lock, donc l’étape refuse une Recipe ou une FeatureRecipe à côté de laquelle se trouve une autre entité — chaque type a son propre répertoire sauf Aggregate, Release et Manifest — et un pull à qui l’on demande d’épingler refuse une telle entité avant que quoi que ce soit ne soit résolu ; Une entité par répertoire expose la règle. Un pull qui n’épingle pas n’écrit rien à côté d’une entité et ne juge pas son répertoire.
aggrega build confronte vos fichiers à ce lock. Un build lit le lock et effectue trois comparaisons :
- Le digest de chaque fichier importé est recalculé et comparé à sa ligne, un fichier
boundary.artifactsexactement comme un fichierartifacts. Un fichier modifié après son épinglage arrête le build avec[CATALOG_ERROR E0026], en nommant l’artefact comme le nomme sa ligne, le fichier importé et les deux digests. - Le digest des fichiers d’une source locale est recalculé et comparé à leurs lignes, comme un seul ensemble, avant que le provider ne lise la source. Un fichier modifié, ajouté ou supprimé depuis l’épinglage arrête le build avec
E0305sous l’instance de composant dont c’est la source, en nommant chacun de ces fichiers et les deux digests ; un fichier à côté de l’entité que la source n’apporte pas n’est pas comparé. Un lock qui n’enregistre aucune ligne pour une source locale ne laisse rien à comparer, comme le décrit A local source no longer matches the pins recorded beside its Recipe (Une source locale ne correspond plus aux épinglages enregistrés à côté de sa Recipe). - Chaque ligne de source est comparée au digest que le lockfile de la Release enregistre pour la même source. Un désaccord arrête le build avec
[FETCH_ERROR E0135], en nommant le lock et les deux digests. Les deux fichiers sont écrits par deux résolutions de la même source — celle de l’étape d’épinglage et celle du pull — de sorte qu’ils divergent lorsque ces résolutions ont obtenu des octets différents, ou lorsque l’un des deux fichiers a été modifié. Des octets différents sous une même version, c’est à cela que ressemble un amont qui a republié une version.
Un lockfile écrit avant la modification provoque l’arrêt en premier, et un pull nomme le fichier. Le lockfile enregistre l’entité d’après ce qu’elle contient, et le lock ainsi que chaque fichier que lisent ces comparaisons en font partie, de sorte qu’un build — ou aggrega pull --verify — qui utilise un lockfile écrit avant qu’un fichier importé, un fichier d’une source locale ou le lock lui-même ne bouge s’arrête avant qu’aucune des trois comparaisons ne s’exécute : The lockfile no longer matches what the release resolves to (Le lockfile ne correspond plus à ce vers quoi la release se résout), en nommant l’entité et les deux digests. Un simple aggrega pull nomme alors le fichier, parce qu’il confronte le lock à ce que l’étape d’épinglage enregistrerait et refuse l’entrée dont l’épinglage ne correspond plus : An entity reads an input the lock beside it records no pin for (Une entité lit une entrée pour laquelle le lock à côté d’elle n’enregistre aucun épinglage).
Là où le lockfile n’a aucun enregistrement du contenu propre de l’entité, ce sont les trois comparaisons qu’un build rencontre. Une Recipe ou une FeatureRecipe que le Manifest nomme par une référence qui est aussi le nom d’un Component ou d’une Feature qu’atteint la Release n’a pas d’entrée propre : l’entrée du lockfile pour cette référence enregistre le Component ou la Feature, de sorte que rien ne bouge dans le lockfile quand les fichiers de la Recipe bougent, et un build et un pull de vérification signalent le fichier modifié avec le code ci-dessus. La comparaison des lignes de source est aussi ce qu’un build rencontre lorsque l’entrée source_artifacts du lockfile est l’enregistrement qui a changé alors que le lock à côté de l’entité n’a pas changé.
Répondre à l’arrêt. Si vous avez modifié le fichier importé volontairement, exécutez aggrega pin sur l’entité : l’étape enregistre le nouveau digest du fichier, et le build suivant l’accepte. Sinon, restaurez le fichier. Une source locale qui a bougé admet les deux mêmes réponses : épinglez à nouveau l’entité, ou restaurez les fichiers que nomme l’arrêt. Pour une ligne de source en désaccord avec le lockfile, restaurez entity.lock depuis le contrôle de version, ou exécutez aggrega pin sur l’entité pour le réécrire.
aggrega pull --verify le vérifie aussi. Un pull de vérification effectue les trois mêmes comparaisons sur les locks à côté des Recipes et FeatureRecipes qu’atteint la Release dans vos répertoires de catalogue, signale chaque épinglage qu’un build refuserait sous le même code et dans les mêmes termes, se termine avec un code non nul s’il y en a un, et n’écrit aucun lock.
Là où aucun lock n’est comparé. Une Recipe ou une FeatureRecipe résolue depuis un registre plutôt que depuis l’un de vos répertoires de catalogue n’a aucun lock que lise un build ; ses sources sont confrontées au seul lockfile de la Release. Et une source écrite à un ref: git est enregistrée dans le lock au commit vers lequel ce ref s’est résolu, alors qu’un build cherche l’épinglage de la source à la version que nomme l’entité, de sorte que cette ligne n’est jamais comparée — ni par un build ni par un pull de vérification. Le lockfile épingle tout de même le commit, et chaque build vérifie l’archive en cache par rapport à lui.
L’enregistrement de confiance des plugins
Certains plugins que l’espace de travail rattache ne façonnent jamais la sortie rendue. Un rattachement plugins.governance dans un rôle ir-verdict ou render-verdict, et chaque rattachement plugins.linter, renvoient un verdict d’acceptation ou de rejet et rien d’autre — aucun de leurs octets n’atteint un artefact. Ils ne font donc pas partie de ce qu’un build reproduit octet pour octet, et le lockfile, qui épingle exactement cela, n’est pas le bon endroit pour eux.
Leurs identités vont plutôt dans un second fichier commité : plugins-trust.yaml, à côté du lockfile. Il porte une entrée par plugin de ce type, enregistrant la coordonnée d’identité du plugin, la version sélectionnée pour lui et le digest de contenu de l’artefact résolu — plus la signature que le pull a vérifiée pour cet artefact, lorsqu’il en a vérifié une, et, lorsque l’éditeur a déprécié cet artefact depuis sa publication, le marqueur que le pull a trouvé et vérifié. Le schéma de l’enregistrement de confiance des plugins décrit le fichier champ par champ.
Commitez plugins-trust.yaml avec le lockfile, pour la même raison que vous commitez le lockfile : un enregistrement conservé hors du contrôle de version est un enregistrement que personne ne peut relire et auquel rien ne peut être comparé. Commité, il constitue une déclaration partagée unique du plugin vers lequel chacun de ces rattachements s’est résolu, et un diff sur ce fichier nomme l’identité qui a changé.
Le fichier n’apparaît que lorsqu’il y a quelque chose à enregistrer. Un espace de travail qui ne rattache aucun plugin renvoyant un verdict ne résout aucune identité de ce type, donc le pull n’écrit aucun fichier et n’en dit rien — une absence, pas un fichier manquant. Lorsque le pull le crée, il nomme le fichier créé et vous indique de le commiter. Un pull ultérieur ajoute une identité que l’enregistrement ne contient pas encore et laisse chaque identité déjà enregistrée exactement telle qu’elle est.
Chaque modification de ce fichier est annoncée, et rien d’autre ne l’est. Un pull qui modifie l’enregistrement affiche une ligne par entrée modifiée, nommant le plugin et la nature du changement : une identité enregistrée pour la première fois, une identité adoptée à la place de celle détenue (en nommant les deux, pour que vous voyiez ce qui a été remplacé), une dépréciation enregistrée sur l’artefact qu’une entrée nomme déjà, une dépréciation retirée d’une entrée, une signature enregistrée sur une entrée ou retirée de celle-ci, ou l’entrée supprimée. La ligne de création ci-dessus est distincte et porte sur le fichier plutôt que sur une entrée, de sorte qu’une première résolution dit les deux : ce fichier est nouveau et doit être commité, et voici les identités qu’il contient désormais.
Un pull qui laisse l’enregistrement exactement tel qu’il était n’en dit rien. Une ligne sur ce fichier signifie donc que le fichier commité a bougé et que son diff mérite d’être lu — ce qui compte ici davantage que pour le lockfile. Tout ce que le lockfile épingle fait aussi partie de ce qu’un build reproduit octet pour octet, de sorte qu’un changement à cet endroit a un second endroit où apparaître ; l’identité d’un plugin de verdict n’en a aucun. Ce fichier est le seul endroit où une barrière remplacée est consignée.
aggrega pull --dry-run n’annonce rien de tout cela, parce qu’il ne modifie rien. Il liste plutôt l’enregistrement parmi les fichiers qu’il écrirait, comme le décrit Prévisualiser ce qu’un pull écrirait.
Une dépréciation est ajoutée à une entrée que l’enregistrement contient déjà, et ce n’est pas la même chose que la réécrire. Si un éditeur déprécie un plugin auquel vous faites déjà confiance, le prochain aggrega pull enregistre le marqueur sur l’entrée existante de ce plugin — la coordonnée, la version et le digest restent intacts, car l’artefact n’a pas bougé et rien de nouveau n’est adopté. Un simple pull peut donc ajouter un bloc deprecation, et seule une mise à niveau explicite change jamais une identité. Un marqueur n’est enregistré que sur l’artefact que l’entrée nomme déjà, et aucun pull ne poursuit un marqueur qui a cessé d’être publié : un marqueur enregistré ne disparaît qu’avec l’entrée qui le portait, c’est-à-dire soit lorsque cette entrée est supprimée, soit lorsqu’une mise à niveau explicite résout à nouveau le plugin et ne trouve aucun marqueur sur les octets que l’entrée enregistre déjà.
La signature vérifiée est enregistrée sur une entrée de la même manière, et chaque pull y répond à nouveau. Le pull vérifie à chaque exécution la signature de chacun de ces plugins par rapport à la politique de confiance de son registre — un plugin servi par un registre est récupéré par sa version à chaque fois, puisque rien ne l’épingle — et enregistre ce qu’il a vérifié sur l’entrée du plugin, là encore sans toucher à l’identité : le mode, le signataire correspondant et le digest du bundle de signature qu’il a mis en cache, la même signature que porte une entrée du lockfile. Contrairement à un marqueur, la réponse remplace ce que contenait l’entrée, et là où le pull n’a vérifié aucune signature — le plugin n’en porte aucune et aucune n’est exigée, ou skip_signature_verification ou un registre advisory l’a admis — l’entrée n’en enregistre aucune. Le bundle de signature vérifié est aussi remis en cache, et une copie en cache qui ne correspond plus à son digest est réécrite. Ainsi, une entrée qui a perdu sa signature, une entrée portant une signature copiée de celle d’un autre plugin, une entrée dont le bundle de signature en cache a été supprimé ou altéré, ou un enregistrement supprimé ou écrit avant qu’une signature ne soit enregistrée, est réparé par le prochain simple aggrega pull. Un build confronte chacun de ces plugins à ce fait : voir L’enregistrement de confiance des plugins sur la page du build.
Une identité résolue en désaccord avec celle enregistrée arrête le pull. Une entrée enregistrée nomme à la fois une version et un digest, donc le changement de l’un ou de l’autre est le même événement : le plugin qui s’exécuterait n’est pas le plugin pour lequel l’enregistrement a été relu. Le diagnostic nomme le plugin, ce que contient l’enregistrement et ce que cette résolution a rapporté, sur les deux axes à la fois — et le pull s’arrête sans toucher à l’enregistrement, de sorte que l’identité relue reste là pour comparaison. Il s’arrête sur la seule version (une republication dont les octets n’ont pas changé) exactement comme il s’arrête sur le seul digest (un nouveau push à la même version).
aggrega pull --verify effectue la même comparaison. Il n’écrit aucun des fichiers qu’un pull commite, donc il n’adopte rien ; il indique si ces fichiers décrivent toujours ce qu’un pull résoudrait aujourd’hui, et l’enregistrement est l’un d’eux. Il confronte aussi la signature de chaque entrée à celle que donne la vérification du plugin par le pull lui-même, et signale une entrée dont un pull enregistrerait, remplacerait ou retirerait la signature — ainsi qu’un plugin pour lequel l’enregistrement ne contient aucune entrée là où un build le refuse faute de signature enregistrée — comme le décrit Il compare les signatures enregistrées, dans les deux fichiers.
Pour adopter une nouvelle identité, demandez-la par son nom : aggrega pull --upgrade --release <release> <plugin>, en nommant le plugin comme le nomme votre rattachement dans .aggrega-config.yaml, sans suffixe de version. Cela résout à nouveau ce seul plugin et réécrit son entrée, en laissant intactes toutes les autres dépendances épinglées et toutes les autres identités enregistrées — et cela fonctionne même si le plugin n’a pas d’épinglage dans le lockfile, parce qu’une cible nommée peut aussi nommer l’un de ces rattachements. Un aggrega pull --upgrade sans cible, qui résout à nouveau chaque dépendance, résout à nouveau et réécrit aussi chaque identité enregistrée. Il en va de même pour aggrega build --upgrade, qui exécute un pull de rafraîchissement complet sans cible et n’a aucun moyen de nommer une cible unique.
Pour retirer une identité, demandez-le aussi par son nom. Détacher un plugin de .aggrega-config.yaml n’efface pas son entrée, et c’est délibéré : un simple aggrega pull n’en retire jamais. Exécutez aggrega pull --upgrade --release <release> <plugin>, en nommant le plugin comme le nomme l’enregistrement — sa coordonnée d’identité, qui est la chaîne qu’affiche l’arrêt ci-dessous — et l’entrée est supprimée, en laissant intactes toutes les autres dépendances épinglées et toutes les autres identités enregistrées. Un aggrega pull --upgrade sans cible supprime chaque entrée qu’aucun rattachement de verdict ne nomme plus, dans la même passe qui résout à nouveau tout le reste.
Retirer la dernière entrée laisse le fichier en place et vide plutôt que de le supprimer. Un enregistrement vide ne contient rien, donc il n’épingle rien et n’arrête rien — comme l’absence d’enregistrement — et conserver le fichier fait apparaître le retrait dans son diff comme un retrait.
Un enregistrement qui ne satisfait pas son schéma arrête chaque commande qui le lit — un build, un lint limité à une release et un pull, y compris un pull qui n’a rien à enregistrer pour son propre compte. Un enregistrement vidé et un enregistrement endommagé sont délibérément différents : le vider est la manière de retirer la dernière entrée, et un enregistrement vidé reste silencieux, alors qu’un fichier dont le contenu ne s’analyse plus est une anomalie et non un enregistrement vide — le lire comme vide ferait de la troncature du fichier un moyen de désactiver la comparaison. Restaurez-le depuis le contrôle de version pour retrouver les identités relues.
Un plugin servi depuis la copie intégrée au binaire du compilateur n’est pas enregistré. Le pull enregistre ce qu’il a acquis — récupéré depuis un registre ou lu depuis le cache — et rien n’est acquis depuis le binaire : ces octets sont identifiés par la version du compilateur qui les porte, donc il n’y a aucune résolution propre à enregistrer. Rattacher un plugin que le binaire porte déjà ne produit donc aucune entrée pour lui. C’est l’enregistrement qui reste cantonné aux artefacts acquis, et non une résolution qui a échoué.
Un build, un lint limité à une release et une validation limitée à une release confrontent la configuration de l’espace de travail à l’enregistrement. Avant que l’un de ces rattachements ne s’exécute, aggrega build, aggrega lint --release et aggrega validate --release — ainsi que les mêmes opérations atteintes via aggrega serve et aggrega mcp — comparent les rattachements de verdict que nomme la configuration aux entrées que contient l’enregistrement. Un plugin dont le digest d’artefact résolu n’est pas celui enregistré est refusé plutôt qu’exécuté. Une entrée de l’enregistrement dont aucun rattachement de verdict configuré ne rend compte arrête l’exécution : une barrière qui a été relue et qui est maintenant absente laisse une sortie impossible à distinguer d’une sortie que cette barrière a approuvée, ce qui est exactement ce que quelqu’un qui lit la sortie ne peut pas voir. L’arrêt nomme le plugin et propose les deux remèdes qui diffèrent selon ce que vous vouliez — rattachez à nouveau le plugin si le retrait était une erreur, ou exécutez la mise à niveau explicite ci-dessus s’il était voulu — et il affiche cette mise à niveau prête à être exécutée. Le sens inverse — un rattachement que l’enregistrement ne contient pas encore — est la première observation décrite ci-dessus, et aucune des deux comparaisons ne s’arrête sur lui ; l’exigence de signature est la seule contrainte à laquelle un rattachement sans entrée n’échappe pas. Les trois mêmes surfaces confrontent chaque plugin qu’elles lisent depuis le cache à la signature qu’enregistre son entrée, lorsqu’elles le chargent, comme le décrit la page du build pour un build. Les portées de lint sur l’ensemble du catalogue et sur une seule entité ne consultent aucun enregistrement.
Une validation est confrontée à l’enregistrement parce qu’elle exécute les mêmes vérifications qu’un build. aggrega validate --release atteint chaque vérification qu’atteint aggrega build, à l’écriture des artefacts près, plugins de barrière compris — c’est ce qui fait que « cela se valide » signifie la même chose que « cela se construit » — de sorte que l’identité du plugin qu’elle exécute est comparée à l’enregistrement exactement comme celle d’un build. Les autres portées d’aggrega validate n’y sont pas soumises : valider l’ensemble du catalogue, une seule entité ou un binaire de plugin ne lit pas du tout les rattachements de plugins de l’espace de travail, donc aucun plugin de verdict ne s’y exécute et il n’y a rien qu’un enregistrement puisse contraindre.
Confronter une configuration à l’enregistrement établit la présence et l’identité, et rien au-delà. Cela établit que chaque barrière que nomme l’enregistrement est toujours rattachée, et que chacune s’exécute à partir de l’artefact enregistré pour elle. Cela n’établit pas qu’une barrière qui s’est exécutée a bien renvoyé un verdict, et un cas de ce type n’est détecté nulle part : un rattachement dont la function nomme un export que le plugin déclare bel et bien, qui n’est pas l’export de verdict que lit son socket, et dont la sortie ne porte aucun champ de premier niveau hors de la forme qu’attend ce socket — l’objet vide étant le cas le plus simple — s’exécute, ne renvoie rien sur quoi fonder un rejet et laisse passer le build. Sa sortie est impossible à distinguer de celle d’une barrière qui approuve, et aucune comparaison avec l’enregistrement ne peut le remarquer, parce que rien dans l’enregistrement n’est faux : le plugin qui s’est exécuté est exactement celui enregistré, et il n’a simplement rien exécuté. Deux cas voisins provoquent bien un arrêt, de sorte que la limite n’est pas plus large qu’elle n’y paraît — une function nommant un export que le plugin ne déclare pas est refusée au chargement du plugin, et une sortie portant un champ de premier niveau que la forme du socket ne déclare pas est refusée plutôt que lue comme une liste de verdicts qui se trouve être vide. Une identité enregistrée ne suffit donc pas à elle seule pour qu’une barrière ait jugé quoi que ce soit.
Le digest enregistré régit les plugins que l’espace de travail résout depuis le cache que remplit aggrega pull, et rien de ce qu’il résout autrement. C’est la résolution que suit normalement un rattachement de verdict — rien ne l’épingle dans le lockfile, donc ses octets proviennent du cache, et c’est lors de cette lecture que le digest résolu est comparé à celui enregistré. Un plugin de verdict que l’espace de travail résout autrement n’atteint jamais cette lecture, et il est régi par ce qui régit la manière dont il s’est résolu plutôt que par l’enregistrement : des octets servis depuis la copie intégrée au binaire du compilateur sont identifiés par la version du compilateur qui les porte, un .wasm placé à côté de son entité de catalogue est un fichier de votre propre répertoire de catalogue, un chemin explicite du système de fichiers est le chemin que vous avez nommé, et un plugin portant un épinglage dans le lockfile est régi par cet épinglage. L’autre moitié de la confrontation d’une configuration à l’enregistrement n’est pas bornée de cette façon : chaque entrée que contient l’enregistrement doit toujours être justifiée par un rattachement configuré, quelle que soit la manière dont ce plugin se résout. L’enregistrement établit donc que les barrières qu’il nomme sont toujours rattachées, quel que soit ce qui les sert, et il établit l’identité d’artefact de celles servies depuis le cache.
Respecter ou mettre à jour
Par défaut, aggrega pull respecte un lockfile existant : une dépendance déjà épinglée se résout exactement vers sa version épinglée (vérifiée par rapport à son digest épinglé), seules les références pas encore épinglées sont résolues et ajoutées, et les épinglages des références que la Release n’atteint plus sont supprimés. Ainsi, un nouveau pull d’une Release inchangée ne fait rien — il reproduit le même lockfile octet pour octet (y compris generated_at). Ajouter une nouvelle dépendance, ou lancer un pull après qu’une modification manuelle a supprimé un épinglage, résout uniquement cette lacune et laisse tous les autres épinglages intacts.
Une dépendance qu’un nouveau pull lit depuis le cache est enregistrée exactement comme l’a enregistrée le pull qui l’a récupérée. Sa ligne conserve la version, le digest du contenu et le manifest_digest — ce dernier tiré du manifest stocké à côté du contenu dans le cache — ainsi que la signature et la deprecation que ce pull a vérifiées auprès du registry. Rien de tout cela n’est consulté à nouveau tant qu’un build accepterait la ligne, et --detail signale une telle dépendance comme cache-reuse ; ainsi, un nouveau pull dont toutes les dépendances sont en cache, sur un lockfile qui enregistre chaque signature exigée par la configuration de confiance et uniquement des signatures qu’un build accepte, écrit le même lockfile, que le registry soit joignable ou non.
Un nouveau pull consulte à nouveau une signature exactement là où un build refuserait la ligne, et il existe deux lignes de ce type.
- Une signature exigée que le lockfile n’enregistre pas. Lorsque la configuration de confiance exige une signature pour une dépendance que le cache fournit et que la ligne du lockfile n’en enregistre aucune — la ligne a été modifiée, le lockfile a été réécrit de zéro sur un cache rempli par un pull antérieur, ou l’exigence a été ajoutée après le pull qui a écrit la ligne — le nouveau pull demande sa signature au registry de cette dépendance, par le digest du manifest stocké à côté d’elle dans le cache, exactement comme il le fait pour une dépendance qu’il récupère, et enregistre la signature vérifiée sur la ligne. Cette ligne est celle qu’un build refuse (No verified signature is recorded for an artifact that requires one (Aucune signature vérifiée n’est enregistrée pour un artefact qui en exige une)), c’est donc un nouveau pull qui lève ce refus. Un registry qui n’attache aucune signature, ou une signature que la configuration de confiance n’accepte pas, interrompt le nouveau pull comme il interrompt un pull qui a récupéré la dépendance. Les paramètres qui permettent à un pull d’admettre une dépendance sans signature laissent une telle ligne en l’état et ne demandent rien à son sujet :
skip_signature_verificationau niveau supérieur, le même interrupteur sur l’entrée propre du registry sauf pour un type que la politique de signature de l’ensemble du workspace exige, et un registry marquéadvisory. - Une signature enregistrée qu’un build n’accepte pas. Lorsque la ligne enregistre une signature dont le bundle de signature en cache a été supprimé ou altéré après le pull qui l’a mis en cache — ou une
signaturecopiée depuis une autre ligne, dont le bundle est intact mais a été créé pour un autre artefact — un build refuse la ligne quoi que dise l’exigence de signature (A cached signature bundle does not match the digest recorded for it (Un bundle de signature en cache ne correspond pas au digest enregistré pour lui), A recorded signature was made for a different artifact (Une signature enregistrée a été créée pour un autre artefact)). Le nouveau pull interroge donc à nouveau le registry de cette dépendance sur sa signature, quoi que dise l’exigence, au moyen de la même vérification que celle d’une dépendance qu’il récupère : ce que cette vérification valide remplace la signature de la ligne, et le bundle qu’elle désigne est remis en cache, une copie en cache qui ne correspond plus à son digest étant réécrite — ainsi la ligne et le cache contiennent ce qu’a laissé le pull qui a récupéré la dépendance. Une signature que la configuration de confiance n’accepte pas interrompt le nouveau pull comme elle interrompt un pull qui a récupéré la dépendance, de même qu’un registry qui n’en attache aucune là où une signature est exigée. Lorsque la vérification n’en enregistre aucune —skip_signature_verificationlà où il s’applique, qui ne demande rien, un registry qui n’attache aucune signature là où aucune n’est exigée, ou un registryadvisoryoù rien n’est vérifié — la signature de la ligne est effacée, ce qu’un build admet avec les mêmes paramètres.
Une ligne dont un build accepte la signature enregistrée n’est pas interrogée à nouveau, pas plus qu’une ligne qui n’en enregistre aucune et pour laquelle rien n’exige de signature.
Une dépendance nommée sans registry, dans un workspace qui ne nomme désormais aucun default_registry, ne peut pas être interrogée. Sa ligne a été liée à un registry par le pull qui a enregistré sa signature, et sans registry par défaut, il n’y a aucun registry à interroger. Lorsqu’une telle ligne enregistre une signature qu’un build n’accepte pas, le nouveau pull s’interrompt avec le refus propre au build, en indiquant qu’aucun registry n’est configuré pour interroger à nouveau la ligne, et laisse le lockfile tel qu’il était. Configurer comme default_registry le registry d’où provient la dépendance et relancer le pull le répare.
Ce que régit ce respect, c’est ce que fournit un registry ou le cache. Une entité qu’un répertoire de catalogue local fournit est résolue depuis ce répertoire, dans la version que déclare son fichier, et l’entrée que le lockfile enregistre pour elle n’est pas consultée au passage. Le lockfile enregistre tout de même une telle entité, vous la verrez donc là — mais modifier cette entrée à la main ne maintient pas l’entité à la version que vous avez écrite, et la réconciliation suivante réécrit l’entrée pour qu’elle corresponde au fichier. Pour changer la version d’une entité fournie localement qu’une Release résout, modifiez le fichier du catalogue plutôt que le lockfile.
Un épinglage désigne des octets, pas un emplacement, donc une entrée de cache qui ne contient plus son épinglage est ignorée plutôt que considérée comme fiable. Une entité modifiée sur place — un nouveau corps sous la même version — laisse dans le cache de contenu le corps antérieur sous ce nom et cette version. Un répertoire de catalogue est lu en premier, donc une entité qu’un tel répertoire fournit encore est épinglée depuis son fichier et l’entrée périmée n’est jamais lue. Le rendu que le pull exécute pour découvrir les entrées externes de la Release lit chaque épinglage comme le fait un build, depuis le répertoire de catalogue qui contient les octets épinglés, et signale l’entrée ignorée avec l’avis qu’affiche aggrega build. Lorsqu’aucun répertoire de catalogue ne fournit l’entité et qu’un registry est joignable, le pull récupère à nouveau la version épinglée, réécrit l’entrée et le signale sur la sortie d’erreur standard, en nommant l’entrée et les deux digests :
reuse: cache entry for <name>:<version> held <digest the entry held>, not the pinned <pinned digest>; refreshed from the registry (pin unchanged)Les octets récupérés sont confrontés à l’épinglage comme pour toute récupération sous un épinglage, donc un registry qui sert d’autres octets sous cette version interrompt le pull, comme décrit ci-dessous. Lorsqu’aucune source ne contient les octets épinglés — aucun répertoire de catalogue ne fournit l’entité, l’entrée de cache contient d’autres octets, et aucun registry ne sert la version épinglée ou l’exécution n’en atteint aucun — le pull et aggrega pull --verify s’interrompent avec E0135 — ou E0133 lorsque le manifest de l’entrée de cache n’est pas celui qu’épingle le lockfile — en nommant chaque source lue et ce qu’elle contenait ; lorsque l’exécution n’a atteint aucun registry, l’interruption nomme aussi l’étape qui récupère à nouveau la version épinglée.
Pour mettre à jour les versions épinglées, exécutez aggrega pull --upgrade --release <release> — cette commande abandonne les épinglages existants et résout à nouveau toutes les dépendances vers les dernières versions satisfaisantes. La mise à jour est l’acte explicite ; le comportement par défaut ne fait jamais flotter une dépendance épinglée. Cela reflète la convention de npm ci / cargo / go build (le comportement par défaut réalise le verrou ; la mise à jour est facultative), et c’est ce qui rend sûr le pull automatique d’aggrega build — le build résout exactement ce qu’épingle le lockfile, sans jamais déplacer une version en silence.
Cette forme sans cible abandonne chaque épinglage enregistré, elle demande donc une confirmation avant de faire quoi que ce soit. Répondez-y à l’avance avec --yes pour une utilisation non interactive ; si l’entrée standard n’est pas un terminal et que --yes est absent, elle refuse plutôt que d’attendre une réponse que personne ne peut donner. Nommer des cibles (aggrega pull --upgrade --release <release> <uri>) conserve chaque épinglage non nommé, donc cette forme ne demande rien. aggrega build --upgrade exécute la forme sans cible et est soumis aux mêmes conditions.
Si les octets d’une version épinglée dans le registry ne correspondent plus au digest que le lockfile a enregistré (une violation de l’immuabilité en amont), pull s’interrompt avec une erreur d’intégrité plutôt que d’adopter en silence les octets modifiés — exécutez --upgrade pour épingler à nouveau délibérément.
Vérifier un lockfile sans l’écrire
aggrega pull --verify --release <release> répond à une question : exécuter aggrega pull maintenant modifierait-il le lockfile, ou le registre de confiance des plugins situé à côté ? Il effectue la résolution qu’effectuerait un pull, compare le lockfile et le registre avec celle-ci, et s’arrête avant que quoi que ce soit qu’un pull valide ne soit écrit — le lockfile, le registre de confiance des plugins et chaque entity.lock restent tels quels. Il se termine avec un code non nul si le lockfile est absent et pour toute différence, en nommant chacune. Les marqueurs de dépréciation ne sont pas comparés, comme décrit ci-dessous. Il est refusé avec --upgrade, avec --dry-run et avec --pin-sources, quelle que soit la valeur donnée à cette option : une vérification n’enregistre pas un épinglage manquant dans un entity.lock et ne s’interrompt pas non plus pour lui, donc l’option ne changerait rien.
Il respecte les épinglages enregistrés exactement comme le fait un pull. Une dépendance que le lockfile épingle se résout vers sa version épinglée et est vérifiée par rapport à son digest épinglé, et une entité qu’un répertoire de catalogue local fournit est résolue depuis ce répertoire, comme le décrit Respecter ou mettre à jour. Ainsi :
- Une référence dont le registry a publié une version plus récente depuis le pull n’est pas une dérive. Un pull conserverait son épinglage, le lockfile est donc toujours celui qu’écrirait un pull ;
aggrega pull --upgradeest la manière d’adopter la version plus récente. - Un registry qui sert désormais des octets différents sous une version épinglée interrompt la vérification avec l’erreur d’intégrité qui interrompt un pull, plutôt que de signaler le changement comme une dérive.
- Une ligne du lockfile modifiée à la main, une Release modifiée et une entité modifiée dans un répertoire de catalogue local sont chacune signalées, car chacune est une différence entre le lockfile et ce qu’un pull résout maintenant.
Il lit et remplit le cache comme le fait un pull. Une entrée que le cache contient sous son épinglage — une entité de catalogue, ou le .wasm d’un plugin — est lue depuis le cache sans interroger de registry, ce qui permet à une vérification de s’exécuter en mode hors ligne sur un workspace qu’un pull connecté a rempli. Une entrée que le cache ne contient pas est récupérée, comme un pull la récupère, et une entrée qui ne correspond plus à son épinglage est traitée exactement comme un pull la traite. Une vérification peut donc ajouter au cache, et elle ne déplace jamais un épinglage.
Il compare les signatures enregistrées, dans les deux fichiers
La signature qu’un pull a vérifiée pour un artefact fait partie de ce qu’il écrit : la signature d’une entrée du lockfile, et celle d’une entrée de plugins-trust.yaml pour un plugin rattaché à un rôle de verdict. Une fois que les épinglages concordent, une vérification confronte chaque signature enregistrée à celle qu’un pull enregistrerait maintenant, et signale chacune qu’un pull enregistrerait là où aucune n’est enregistrée, remplacerait ou effacerait, sous A recorded signature is not the one a pull would record (Une signature enregistrée n’est pas celle qu’un pull enregistrerait). Chacune de ces entrées, dans l’un ou l’autre fichier, est nommée dans la même exécution.
Le choix des entrées du lockfile qu’elle consulte appartient au pull lui-même. Un nouveau pull interroge un registry sur la signature d’une entrée exactement là où le décrit Respecter ou mettre à jour, et une vérification reprend ce même choix :
- Deux sont signalées sans interroger de registry, car un pull les réécrit quoi que réponde le registry : une entrée que le cache fournit et qui n’enregistre aucune signature là où la configuration de confiance en exige une — le pull enregistre la signature de l’artefact, ou s’arrête là où aucune ne peut être établie — et une entrée dont la signature enregistrée a été créée pour un autre artefact, que le pull remplace par celle de l’artefact lui-même.
- Toute autre entrée qu’un pull consulterait à nouveau est interrogée, car seule la réponse du registry indique si le pull la modifierait : une entrée dont cette vérification a récupéré les octets, et une entrée dont le bundle de signature en cache a été supprimé, est illisible ou a été altéré. La vérification interroge le registry, comme le ferait le pull, et signale l’entrée là où la réponse enregistre, remplace ou efface sa signature. Le bundle de signature qu’elle a vérifié est mis en cache comme un pull le met en cache, donc une entrée dont le bundle en cache a été supprimé, alors que son registry sert toujours la signature enregistrée, passe la vérification et laisse le cache réparé.
Une entrée dont un build accepte la signature enregistrée, et une entrée qui n’en enregistre aucune et pour laquelle rien n’exige de signature, ne sont pas interrogées, ni par un pull ni par une vérification.
Le registre de confiance des plugins est confronté au même pull. Chaque pull vérifie auprès de son registry la signature de chaque plugin rattaché à un rôle de verdict, et une vérification fait de même, en signalant une entrée dont cette vérification enregistrerait, remplacerait ou effacerait la signature. Un plugin pour lequel le registre ne contient aucune entrée est signalé là où un build le refuse parce qu’il n’enregistre aucune signature, car un pull écrit une entrée portant sa signature et le build refuse le plugin jusque-là. Tout autre est une première observation, qu’une vérification ne signale pas, de même qu’elle ne signale aucune identité que le registre ne contient pas encore. En mode hors ligne, une vérification n’interroge aucun registry sur ces plugins, et Hors ligne décrit ce qu’elle signale à la place.
Les marqueurs de dépréciation ne sont pas comparés. Un marqueur attaché à un artefact après le pull relève de l’état du registry, et il évolue sans que rien ne change dans le workspace ; une vérification qui échouerait à cause de lui ferait échouer un contrôle portant sur des fichiers que vous n’avez pas touchés. Pour la même raison, un marqueur enregistré avertit un build plutôt que de l’arrêter. Un pull peut donc enregistrer un marqueur sur une entrée qu’une vérification a validée.
Prévisualiser ce qu’un pull écrirait
aggrega pull --dry-run --release <release> résout les dépendances exactement comme un pull ordinaire puis, au lieu d’écrire, affiche ce qu’il aurait écrit : un en-tête nommant le chemin de chaque fichier, suivi du contenu que ce fichier contiendrait.
aggrega pull --dry-run --release release.yamlIl nomme chaque fichier, pas seulement le lockfile. Le lockfile, l’entity.lock à côté de chaque Recipe et FeatureRecipe dont les épinglages enregistrés bougeraient sous --pin-sources, et le registre de confiance des plugins apparaissent tous dans le même rapport, car un aperçu qui ne montrerait que le lockfile vous apprendrait que le lockfile est tout ce qui bouge. Un pull qui s’interromprait sur une entité non épinglée s’interrompt aussi sous --dry-run, pour la même raison : ce que montre un aperçu est ce que ferait le pull. Les fichiers qu’un pull laisserait identiques octet pour octet n’apparaissent pas du tout — un nom dans le rapport signifie que ce fichier est sur le point de changer. La dernière ligne les compte, et un workspace qu’un pull ne modifierait pas signale un total de zéro.
Rien ne bouge sur le disque. Aucun lockfile n’est écrit ni créé, aucun verrou d’entité n’est écrit ni supprimé, et aucun registre de confiance n’est créé ni modifié. Lorsqu’une capacité est fournie par plus d’un plugin de provider et que rien n’a choisi entre eux, l’exécution s’interrompt en nommant ce qu’il faut fournir plutôt que de proposer d’écrire le choix dans votre configuration — un aperçu ne modifie pas un fichier de configuration au passage.
La résolution elle-même s’exécute quand même, donc le cache se remplit quand même. Les entrées externes qu’une Release consomme sont un produit de son rendu, et une exécution qui renoncerait à résoudre n’aurait rien à signaler, donc --dry-run récupère et stocke exactement comme le fait un pull. Le contenu sous .aggrega/cache n’est lu qu’à travers les épinglages qu’enregistre un lockfile, donc le remplir ne change rien à ce qu’un build résout ; ce que montre une exécution à blanc est ce qu’un pull écrirait.
Un --upgrade sans cible ne demande rien avec cette option. La confirmation existe parce qu’une actualisation complète abandonne chaque épinglage enregistré, et qu’un aperçu n’en abandonne aucun — donc aggrega pull --dry-run --upgrade --release <release> est la forme à utiliser lorsque ce que vous voulez savoir, c’est ce que vous coûterait une actualisation, et elle s’exécute sans réponse.
Il n’est pas accepté avec --verify, qui n’écrit déjà aucun de ces fichiers. La paire laisserait l’option sans effet tout en donnant l’impression qu’elle a fait quelque chose, elle est donc refusée plutôt qu’ignorée.
Une chose qu’un aperçu avec épinglage ne peut pas toujours montrer en entier, et il le dit quand cela arrive. Un pull à qui l’on demande d’épingler réécrit l’entity.lock à côté de chaque Recipe et FeatureRecipe puis effectue le rendu de la Release pour découvrir ses entrées externes ; un aperçu laisse ces verrous en l’état, donc là où un épinglage qui y est enregistré est devenu périmé — vous avez modifié un fichier importé depuis qu’il a été épinglé, par exemple — ce rendu est confronté au digest périmé que le verrou non écrit enregistre encore, et s’arrête. Tout le reste du rapport est exactement ce qu’un pull écrirait ; seuls les épinglages d’entrées externes du lockfile signalé sont incomplets. L’exécution le dit à la fois dans sa sortie et dans ses diagnostics plutôt que de vous remettre un lockfile qui semble complet. Une première résolution d’un workspace n’est pas concernée, car il n’existe encore aucun digest enregistré par rapport auquel quoi que ce soit pourrait être périmé.
La composition que décrivent ces épinglages
Un lockfile épingle ce qu’un build de cette Release consommera, donc la résolution dessine la composition que dessine ce build : elle résout les documents, applique les transformations que déclarent les rattachements du workspace, et soumet le résultat aux contrôles qu’un build effectue sur un graphe achevé. Il en découle deux choses, et toutes deux surviennent lors de la passe qui écrit le lockfile plutôt que lors du premier build qui le lit.
Une composition que ces contrôles rejettent interrompt le pull. Une arête uses: dont la cible ne satisfait pas le selector: de son socket, une Feature rattachée à un composant que son appliesTo: n’admet pas, et toute autre violation que ces contrôles signalent arrêtent cette commande, avec le diagnostic qu’affiche un build des mêmes documents — et l’interruption nomme chaque constat en une seule exécution plutôt que le premier seulement, de sorte qu’une passe vous remet toute la liste à corriger. Elle survient avant l’écriture, donc <release-stem>.lock et plugins-trust.yaml restent exactement tels qu’ils étaient, et une Release qui ne se compile pas n’est jamais enregistrée comme une Release résolue proprement. Ce que cela ne couvre pas, ce sont les rattachements qui renvoient un verdict : aucun rattachement ir-verdict ou render-verdict ne s’exécute ici, donc un verdict de rejet arrête le build, le lint limité à une release ou la validation limitée à une release qui le déclenche, plutôt que cette commande.
Un rattachement dans un rôle qui façonne le graphe s’exécute pendant cette passe, donc un plugin qui ne se résout pas interrompt le pull. Un rattachement label-transform décide des labels des nœuds avant que quoi que ce soit ne soit comparé à eux, et un rattachement annotation-transform injecte des annotations qui se développent en rattachements de Feature — tous deux modifient ce que contient le graphe, donc dessiner le graphe implique de les déclencher, et les déclencher implique de disposer des octets propres à chaque plugin. Un plugin dont cette passe ne peut obtenir les octets interrompt l’exécution, en nommant le plugin et ce qui n’a pas pu être trouvé pour lui — le même refus qu’oppose un build du même workspace lorsqu’il ne peut pas les obtenir. Ce qu’elle déclenche est la liste de rattachements que cette passe vient de résoudre, avec les paramètres et les fichiers de définition que le lockfile enregistre pour qu’un build ultérieur les reconstitue, de sorte que les deux passes exécutent le même rattachement sur la même entrée.
Un Plugin qu’une étape de pipeline nomme et que rien ne contient interrompt aussi le pull. Chaque Plugin que nomme la pipeline d’une Recipe ou d’une FeatureRecipe est résolu avec les autres dépendances de la Release — depuis un répertoire de catalogue, la copie intégrée au binaire du compilateur, le cache de contenu ou le registry — et un Plugin qu’aucune de ces sources ne contient est un Plugin qu’un build ne pourrait pas charger non plus. Le pull s’arrête donc avant d’écrire quoi que ce soit, en nommant le Plugin et la Recipe ou FeatureRecipe dont le pipeline le nomme, avec la condition que soulève un build lorsqu’il atteint cette étape (A plugin reference is not a Plugin entity (Une référence de plugin n’est pas une entité Plugin)). Cela vaut pour chaque Recipe et FeatureRecipe que le Manifest lie, y compris celle que rien dans cette Release ne rattache, car chacune est résolue et épinglée, qu’elle soit rendue ou non. Publiez le Plugin, ou placez-le dans un répertoire de catalogue avec son .wasm compilé à côté, puis relancez le pull.
Cette interruption et une exécution dégradée sont des issues différentes, délibérément. Un rendu qui ne peut pas aboutir — celui que décrivent à la fois Comment la résolution trouve les entrées externes et Hors ligne — laisse chaque épinglage de dépendance correct, donc les épinglages sont écrits et le manque est signalé. Une composition que les contrôles rejettent n’est pas un manque dans ce qui a été résolu : c’est une Release qui ne se compile pas, donc rien n’est épinglé pour elle et l’exécution s’arrête.
Le cache
Le contenu récupéré est stocké sous .aggrega/cache, réparti entre une sous-arborescence entities/ pour les entités de catalogue, une sous-arborescence source-artifacts/ pour les artefacts sources, et une sous-arborescence inputs/ pour les entrées externes que consomme un rendu. L’emplacement d’une entité de catalogue est nommé d’après son type, sa coordonnée et sa version — de sorte qu’un Component et une Recipe qui partagent une coordonnée et une version conservent deux emplacements —, celui d’un artefact source d’après l’endroit d’où il a été récupéré, sa version et un préfixe du digest de son contenu, et celui d’une entrée externe d’après le digest de son contenu ; ce qu’un build lit dans chacun d’eux est vérifié par rapport à ce qu’enregistre le lockfile. Des épinglages de version identiques partagent donc un emplacement entre plusieurs Releases. Chaque emplacement d’artefact source contient l’archive faisant autorité, une extraction régénérée et un petit fichier de métadonnées ; l’extraction est régénérée à chaque lecture, donc la sortie du build dépend de l’archive et du lockfile, pas de l’état des fichiers extraits.
Chaque nom que le cache dérive d’une valeur est accepté à la fois par Windows, Linux et macOS. Une coordonnée, une version, un hôte de registry ou un digest contient des caractères qu’un nom de fichier ne peut pas contenir : le / entre les parties d’une coordonnée, le : avant une version, à l’intérieur de sha256: et avant le port d’un registry. Chaque valeur — un type, une coordonnée, une version, un hôte de registry ou un digest — est donc transcrite avant de devenir un nom de répertoire ou de fichier — une lettre minuscule, un chiffre, ., _ et - sont écrits tels quels, et tout autre caractère est écrit sous forme d’échappement commençant par +. Le Component core/devtool/adminer:1.0.0 à la version 1.0.0 correspond à l’emplacement entities/+zx000043omponent/core+zsdevtool+zsadminer+zx00003a1.0.0/1.0.0/, et un emplacement nommé d’après un digest de contenu est sha256+zx00003a<hex>. Une lettre majuscule est échappée aussi, de sorte que deux coordonnées qui ne diffèrent que par la casse conservent deux emplacements sur un système de fichiers qui ignore la casse ; un nom que Windows réserve à un périphérique, comme con, voit sa première lettre échappée ; et aucun nom ne se termine par un point. Deux valeurs différentes ne partagent jamais un nom, et une valeur a le même nom sur chaque machine. aggrega cache status liste chaque entrée d’après les valeurs à partir desquelles ses noms ont été transcrits — une entité de catalogue d’après sa coordonnée, sa version et son type — plutôt que d’après les noms transcrits.
Une entrée d’archive conserve le nom que lui a donné son éditeur, donc sous Windows, une entrée que Windows ne peut pas contenir est refusée. Les fichiers que contient l’archive d’un artefact source ou d’une entité de catalogue sont disposés sous les noms que l’archive leur donne, et non transcrits par le cache. Lorsque l’extraction s’exécute sous Windows, une entrée contenant une partie que Windows ne peut pas contenir telle qu’elle est écrite — un nom qu’il réserve à un périphérique, comme NUL ou aux, quelle que soit la casse et avec ou sans extension, ou une partie se terminant par un point ou une espace — est refusée avec E0340, en nommant l’entrée, et rien de cette archive n’est disposé. Sous Linux et macOS, une telle entrée est disposée sous le nom qu’elle porte. Une entrée qui remonte hors du répertoire de l’extraction est refusée sur chaque machine.
L’emplacement d’une entité de catalogue n’est une entrée qu’avec son manifest. L’emplacement contient le contenu qu’un registry a servi et, à côté, le manifest qui décrit ce contenu. Un emplacement qui ne contient que le contenu — une récupération interrompue entre les deux écritures, ou un fichier placé là à la main — n’est pas une entrée : un pull, et un pull de vérification, le redemandent au registry de l’entité là où il est joignable, tandis qu’un build, qui ne récupère jamais rien, traite l’entité comme manquante, comme le fait un pull lorsqu’aucun registry n’est joignable.
Ce qui parvient au cache est soumis à deux choses : la forme que décrit le schéma propre de l’entité, et l’emplacement que le cache lui attribue. Un corps récupéré depuis un registry passe par le schéma de son type — le même contrôle que celui qui le relit — avant d’être mis en cache, donc une entité ou une bibliothèque publiée que le registry sert et que son propre schéma refuse interrompt le pull, en nommant ce qui a été récupéré, plutôt que d’être mise en cache puis rencontrée plus tard comme une anomalie. Et une valeur à partir de laquelle un emplacement de cache est construit et qui placerait un fichier en cache ailleurs qu’à l’endroit que nomme la valeur — une version qui est un chemin plutôt qu’une version, un chemin url de source ou un module_subdir qui remonte au-dessus de sa place — est refusée là où l’emplacement est construit, en nommant la valeur en cause. Une valeur écrite dans une Recipe ou une FeatureRecipe dont vous êtes l’auteur est soumise de la même manière au moment où l’emplacement de cache est construit à partir d’elle — et le module_subdir d’une source git plus tôt, avant que le dépôt ne soit récupéré, comme décrit ci-dessous.
Un dépôt git est archivé depuis son propre checkout. Pour une source git-repository, le pull extrait le dépôt au commit qu’il épingle et archive le répertoire que nomme module_subdir, ou le dépôt entier. Un module_subdir qui remonte au-dessus du dépôt tel qu’il est écrit — ../shared, ou ..\shared — est refusé avant que le dépôt ne soit récupéré, avec E0307 citant la valeur, donc rien à côté du checkout n’est lu. Un lien symbolique que le dépôt committe est archivé comme le fichier ou le répertoire vers lequel il pointe lorsque celui-ci se trouve à l’intérieur du dépôt — module_subdir lui-même peut être un tel lien. Un lien qui mène hors du dépôt interrompt le pull avec E0321, en nommant le lien et l’endroit où il mène, et rien n’est mis en cache, de sorte qu’un dépôt depuis lequel vous faites un pull ne peut pas amener le pull à copier un fichier de votre machine dans l’artefact. Le checkout est supprimé dès que le pull s’arrête, donc le message nomme le lien par son emplacement dans le dépôt, ainsi que le dépôt et la révision que nomme la source, plutôt qu’un répertoire qui n’existe plus. C’est au dépôt de modifier le lien. La frontière du workspace énonce la règle qui s’applique ici.
Le cache est ancré au workspace plutôt qu’au répertoire depuis lequel vous avez exécuté la commande, donc un workspace a un seul cache, et un pull exécuté depuis un sous-répertoire remplit le même stockage que celui que lit un build exécuté depuis la racine.
Un pull pour lequel aucun workspace n’a été trouvé ni nommé est refusé avant que quoi que ce soit ne soit récupéré. Lorsque rien ne nomme de racine et que la découverte n’ancre rien — depuis le dossier dans lequel vous l’exécutez ou, pour une Release nommée par un chemin absolu, depuis le dossier propre à cette Release — le dossier serait la racine, et un cache écrit sous celui-ci en ferait un workspace. Le pull s’arrête donc, n’écrit ni lockfile ni cache, et nomme le dossier ainsi que les deux manières d’en sortir : nommez votre workspace avec --workspace-root ou AGGREGA_WORKSPACE_ROOT, ou donnez à ce dossier un .aggrega-config.yaml contenant un bloc workspace:. L’outil de pull d’aggrega mcp, appelé sans workspace_root sur un serveur lancé sans racine, est refusé de la même manière ; Configuration liste les autres commandes pour lesquelles cela vaut.
Compiler là où le réseau est inaccessible
Comme cette commande est la seule étape qui accède à l’extérieur, une seule exécution connectée suffit pour rendre locaux tous les builds ultérieurs. Cette exécution écrit le lockfile et remplit le cache du workspace avec les octets que désignent ces épinglages, et un build n’a ensuite besoin de rien d’autre.
Trois choses sont transportées vers la machine déconnectée :
- La Release et son lockfile. Committez
<release-stem>.lockà côté de la Release ; c’est lui qui indique au build vers quelle version et quel digest chaque dépendance s’est résolue. plugins-trust.yaml, lorsque le workspace rattache un plugin qui renvoie un verdict. Un build compare les rattachements de verdict que nomme sa configuration à ce registre avant qu’aucun d’eux ne s’exécute, donc emporter le registre est ce qui soumet le build déconnecté aux identités qui ont été revues et aux signatures que le pull a vérifiées pour elles. Committez-le à côté du lockfile, comme le décrit Le registre de confiance des plugins.- Le répertoire du cache. Les entités, les artefacts sources et les entrées épinglées se trouvent tous sous ce répertoire, et tout ce qu’un répertoire
catalog_dirslocal ne fournit pas y est lu.
Lancez le build sur la machine déconnectée comme d’habitude. Activer le mode hors ligne sur cette machine en vaut la peine même si un build sur un lockfile complet lit sa clôture depuis le cache : cela transforme un éventuel accès réseau en un refus immédiat qui nomme le mode, plutôt qu’en une tentative de connexion qui doit d’abord expirer. Tout ce que le cache ne contient pas, et toute entrée externe que le lockfile n’épingle pas, interrompt le build en nommant ce qui manque et la résolution qui l’épinglerait — rien n’est récupéré en silence pour combler le manque.
Une machine isolée du réseau et un workspace hors ligne sont des affirmations différentes, et la différence mérite d’être conservée. Une machine derrière une isolation réseau peut contenir une copie locale d’un registry, ou un catalogue catalog_dirs contenant tout ce dont elle a besoin, auquel cas un pull ordinaire sur cette machine peut être satisfait sans aucun accès à l’extérieur. Le mode hors ligne décrit ce à quoi une commande peut accéder, pas ce que contient la machine ; Hors ligne expose ce qu’il refuse et ce qu’il laisse en l’état.
Hors ligne
En mode hors ligne — la clé de premier niveau offline dans un fichier de configuration, AGGREGA_OFFLINE dans l’environnement, ou --offline sur la ligne de commande — aggrega pull refuse l’accès au réseau. Le refus se produit avant toute tentative de connexion plutôt que sous la forme d’un délai expiré au milieu d’une récupération, donc un pull hors ligne n’atteint aucun registry et aucune source distante. Lorsqu’un fichier committé ou une variable exportée a activé le mode et que vous voulez le contourner pour une commande, --offline=false autorise le réseau pour cette seule exécution.
--upgrade est refusé purement et simplement dans ce mode, et c’est la seule option ici qui l’est. Une actualisation complète fait flotter chaque dépendance vers la version la plus élevée qu’un registry propose actuellement, elle doit donc demander à un registry ce qu’il sert actuellement. Un pull ordinaire, non : il respecte les épinglages qu’il enregistre déjà, ne résout que ce qui n’en a pas, et peut donc être satisfait à partir de ce que contient la machine. Le refus indique lequel des trois endroits a activé le mode et comment autoriser le réseau pour une exécution.
La résolution ne puise alors que dans ce que la machine contient déjà : la pile de recherche catalog_dirs et le cache sous .aggrega/cache. Avec un catalogue et un cache qui satisfont chaque référence, un pull hors ligne se termine normalement et écrit un lockfile ordinaire. Le lockfile enregistre l’URI, la version résolue et le digest de chaque dépendance, et jamais lequel de ces endroits a servi les octets — donc un pull hors ligne et un pull en ligne qui résolvent les mêmes versions écrivent le même lockfile.
Une dépendance qu’un pull hors ligne ne peut pas satisfaire localement l’interrompt. L’entrée n’est jamais ignorée :
- Une entité de catalogue qui ne se résout nulle part interrompt le pull, en nommant la référence et l’endroit d’où elle a été référencée, de sorte que la dépendance manquante et ce qui l’a demandée sont tous deux nommés.
- Une
source:distante interrompt le pull, en nommant la source et en vous indiquant soit d’autoriser l’accès au réseau, soit de remplir le cache depuis un environnement connecté. - Une dépendance que le cache contient et dont le lockfile n’enregistre pas la signature exigée, ou dont un build n’accepte pas la signature enregistrée, interrompt le pull avec le refus hors ligne, en nommant la dépendance : enregistrer la signature implique d’interroger son registry, comme le décrit Respecter ou mettre à jour. Autoriser le réseau pour cette seule exécution l’enregistre. Une signature enregistrée qu’un build accepte n’est pas consultée à nouveau, elle n’arrête donc pas un pull hors ligne.
Une entrée externe est la seule chose qui n’interrompt pas, et elle le signale à la place. Le rendu qui les trouve ne peut pas récupérer ce qui n’est pas déjà stocké, donc un pull hors ligne sur une Release avec une entrée externe non épinglée se termine, écrit chaque épinglage de dépendance qu’il a résolu, et signale trois choses : que le rendu n’a pas abouti, ce qu’il a épinglé, et qu’un build de cette Release s’interrompra en nommant l’URL. Les épinglages de dépendances qu’il a écrits sont corrects — rien en eux ne dépendait du rendu — ils sont donc conservés plutôt que jetés pour qu’un lecteur les reproduise.
C’est délibéré et non une lacune, et il n’existe aucun interrupteur pour cela. Un pull qui jetterait un travail correct vous coûterait la partie qui a réussi ; un pull qui resterait silencieux vous remettrait un lockfile qui semble complet et ne l’est pas. Le signaler est la seule issue qui vous laisse en mesure d’agir : relancez le pull depuis un environnement connecté, ou depuis un environnement dont le cache contient déjà le contenu, et la même commande l’épingle.
Ainsi, un pull hors ligne est un refus de toucher au réseau plutôt qu’un résultat réduit pour tout ce que nomme un document, et pour les entrées externes, c’est une résolution achevée qui vous dit ce qu’elle n’a pas pu atteindre. Un lockfile qui existe est un lockfile dont la résolution des dépendances s’est achevée ; savoir si ses entrées externes sont complètes, c’est ce que vous dit la sortie propre du pull, et ce à quoi un build le soumet ensuite.
--verify en mode hors ligne couvre moins, et le signale. Demander où pointe aujourd’hui une ref de source enregistrée implique d’atteindre son dépôt distant, ce que le mode hors ligne refuse. Un --verify hors ligne contrôle donc les dépendances épinglées et saute cet axe, et il affiche une ligne qui le dit plutôt que de signaler une correspondance qu’il n’a jamais établie. Une signature enregistrée que seul son registry peut confirmer — sur une entrée du lockfile dont le bundle de signature en cache a été supprimé ou altéré — est sautée de la même manière, sur une ligne qui nomme chacune de ces entrées :
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 itUne signature enregistrée qu’un pull réécrirait quoi que réponde le registry est tout de même signalée hors ligne, car aucune réponse n’est nécessaire pour le savoir, comme le décrit Il compare les signatures enregistrées, dans les deux fichiers.
Un plugin rattaché à un rôle de verdict et servi par un registry est le point où une vérification hors ligne et un pull hors ligne se séparent. Un tel plugin n’est jamais épinglé dans le lockfile, donc chaque pull résout son .wasm depuis son registry, et un pull hors ligne sur un workspace qui en rattache un s’arrête là, en nommant le plugin comme un plugin dont il n’a pas pu résoudre le .wasm — même lorsque le cache de contenu le contient, et que ce registry soit marqué advisory ou qu’il saute la vérification des signatures, ou non. Une vérification hors ligne, elle, ne demande rien au registry sur le plugin : elle lit le plugin depuis le cache de contenu, comme le lit un build, et s’arrête là où le cache ne contient pas son .wasm ou en contient un qui ne correspond plus au digest que nomme son manifest publié. Elle confronte toujours l’identité du plugin au registre de confiance des plugins et revérifie ses fonctions hôtes par rapport à ce .wasm, et elle s’interrompt là où l’un ou l’autre diverge, exactement comme le fait une vérification connectée. Elle signale le plugin là où un pull réécrit son entrée quoi que réponde le registry, c’est-à-dire là où un build refuse le plugin à cause de son entrée : parce qu’il n’enregistre aucune signature, son entrée n’en enregistrant aucune ou le registre ne contenant aucune entrée pour lui, ou parce que la signature qu’enregistre son entrée a été créée pour un autre artefact, que le pull remplace par celle du plugin lui-même. Toute autre entrée — une entrée dont un build accepte la signature, et une entrée dont le bundle de signature en cache a été supprimé ou altéré — elle la nomme sur une ligne indiquant que sa signature n’a pas été contrôlée, et ne signale rien sur cette signature :
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 itAinsi, une vérification hors ligne passe sur une entrée dont un pull connecté remplacerait ou effacerait la signature — une entrée dont le signataire a été modifié à la main, par exemple, ou une entrée à laquelle son registry n’attache plus de signature — et cette ligne est la seule chose qui le signale. Une vérification sur une machine isolée du réseau reste disponible ; ce qu’elle ne vous dit pas, c’est si une ref a bougé depuis, ou si une signature sautée serait enregistrée à nouveau. Un contrôle qui ne lit que le code de sortie ne couvre ces cas que lorsque la vérification s’exécute connectée.
Intégration avec aggrega build
- Vérification.
aggrega buildvérifie chaque dépendance résolue par rapport au lockfile et s’arrête en cas de dérive : une entité, une bibliothèque ou un plugin dont le contenu ne correspond plus à son épingle, une référence que la Release atteint désormais et que le lockfile n’épingle pas, ou une qu’il épingle et que la Release n’atteint plus, ainsi qu’un fichier de Release modifié depuis le pull. Exécutezaggrega pull --release <release>, la commande qu’affiche l’arrêt, pour y remédier : le pull résout la Release dans son état actuel, réécrit les épingles qui ont bougé et conserve toutes les autres, de sorte que rien ne flotte que vous n’ayez pas modifié. Lorsque ce qui a bougé est un fichier sous la source locale d’une Recipe, le pull indique d’abordaggrega pinpour cette entité, comme le décrit Le lock d’entité. Un lockfile que cette commande vient d’écrire passe cette vérification, car la commande exécute la même vérification avant de l’écrire ; un build qui s’arrête sur une dérive juste après un pull a reçu des entrées différentes de celles du pull — un répertoire--catalogpassé à l’un et pas à l’autre, ou une configuration de workspace modifiée entre les deux —, exécutez donc les deux sur les mêmes entrées.aggrega validate --releaseet toute sélection d’aggrega inspectqui résout une Release soumettent le lockfile à la même vérification et refusent avec le même arrêt, de sorte qu’aucun des deux ne laisse passer un lockfile qu’un build refuse. - Pull automatique. Si le lockfile est absent et que
auto_pullvaut true,aggrega buildexécute d’abord le pull automatiquement. Siauto_pullvaut false, ce qui est sa valeur par défaut, le build s’arrête et vous demande d’effectuer le pull. Le pull qu’exécute un build suitpin_sources_at_pull, de sorte que sur une entité non épinglée il s’arrête exactement comme un pull. L’étape de pull qu’exécute un build est celle que décrit cette page, de sorte qu’un build qui remplit un lockfile existant s’arrête sur une ref de source déplacée exactement commeaggrega pull— voir Déterminisme et intégrité. - Hors ligne. En mode hors ligne,
aggrega buildn’utilise que ce que la machine détient déjà et refuse l’accès au réseau avant toute tentative de connexion. Une référence dont le cache ne détient pas le contenu arrête le build au lieu d’échouer au milieu d’un téléchargement, et un build sans lockfile auquel il n’est pas demandé d’en remplir un s’arrête en nommant le pull qui le remplirait, exactement comme en ligne.--auto-pulln’est pas refusé : le remplissage qu’il demande est le pull que décrit cette page, de sorte que, pour des entités de catalogue déjà en cache ou présentes dans un catalogue local, il écrit le lockfile sans contacter de registre — une Recipe dont le chart est récupéré depuis une source distante est résolue à nouveau, et s’arrête donc hors ligne même lorsque le cache détient ce chart —, et une référence qu’aucun des deux ne détient — ou une référence en cache dont le lockfile n’enregistre pas la signature requise, ou dont un build n’accepte pas la signature enregistrée — l’arrête avec le refus propre au pull, qui nomme cette référence.--upgradeest refusé, pour la raison qu’indique Hors ligne. - Recherche dans le catalogue. Le pull respecte
catalog_dirsde.aggrega-config.yamlmême lorsqu’aucun--catalogn’est fourni — ainsi que les répertoires propres d’une Release lorsque la configuration lui en attribue sousworkspace.releases— et résout la même pile de recherche où la première correspondance l’emporte queaggrega build, de sorte que les dépendances qu’il épingle correspondent à ce que le build recherche. Un répertoire listé qui n’est pas un répertoire — rien n’existe à cet endroit, par exemple — est refusé par les deux commandes avant que quoi que ce soit ne soit résolu ou écrit, en nommant l’entrée ainsi que le fichier de configuration et la ligne qui la listent, comme le montre D’où sont lues les entités locales.
Comment la résolution trouve les entrées externes
Rien dans cette section ne modifie la règle ci-dessus — il n’existe toujours qu’un seul moment où quoi que ce soit est épinglé, et c’est cette commande. Elle décrit comment la commande atteint le troisième des trois types, ce qui importe lorsque vous intégrez la résolution dans un pipeline, lisez une exécution dégradée ou cherchez à comprendre pourquoi cette commande effectue un rendu.
Une entité de catalogue et un artefact source sont chacun nommés dans un document ; une entrée externe ne l’est pas. Résoudre les deux premiers consiste à lire ce que vous avez écrit. Une entrée externe est nommée par un provider, au milieu d’un rendu, et les URL qu’il nomme découlent des valeurs rendues — une entrée de valeurs absente laisse non compilé tout un sous-arbre du schéma d’un chart et non demandée chaque référence distante de ce sous-arbre. Aucune lecture de la Release ne peut énumérer l’ensemble.
La commande fait donc deux choses en une seule passe : elle résout et épingle la fermeture que nomment les documents, puis effectue le rendu de cette fermeture pour voir quels documents distants les providers demandent. Les artefacts rendus sont abandonnés et les épingles sont conservées. Les deux sont internes à l’unique commande, et aucun n’est un second moment où quelque chose pourrait être épinglé — il y a une seule écriture du lockfile, et elle contient chaque épingle.
Deux conséquences sont à connaître avant d’intégrer la résolution dans un pipeline automatisé comme une étape peu coûteuse. Elle coûte plus cher qu’une résolution qui ne lit que des documents, parce qu’elle effectue un rendu. Et elle peut échouer pour une raison qui ne pourrait pas faire échouer une résolution limitée aux documents : un provider qui ne peut pas effectuer le rendu de cette Release. Dans ce cas, les épingles des dépendances sont tout de même écrites, car rien les concernant ne dépendait du rendu, et le diagnostic nomme l’étape qui s’est arrêtée, ce qui a été épinglé, et le fait qu’un build s’arrêtera en nommant l’URL non épinglée. L’exécution n’est pas perdue, et Hors ligne montre le même résultat atteint par un autre chemin.
Le rendu soumet aussi le lockfile à la comparaison qu’applique un build, avant que quoi que ce soit ne soit écrit. Il exécute la séquence propre au build, et compare donc le lockfile que cette commande s’apprête à écrire avec ce à quoi se résout un build de la même Release, exactement comme un build compare un lockfile qu’il trouve sur le disque. Un lockfile que cette comparaison refuse n’est pas écrit — pas plus que tout ce que la commande aurait écrit ensuite —, et la commande s’arrête en indiquant que la résolution et le build sont en désaccord sur ce dont dépend la Release, suivi de chaque entrée que la comparaison a nommée. Rien dans vos fichiers ne peut en être la cause, et une nouvelle résolution aboutirait au même désaccord ; signalez-le donc avec la Release plutôt que de réessayer. C’est le seul échec de rendu qui empêche l’écriture, et c’est pourquoi un build de la même Release, sur les mêmes entrées, ne signale pas de dérive sur un lockfile écrit par cette commande.
Il n’existe aucune option pour ignorer le rendu. Une telle option préserverait, à titre de choix, exactement la surprise qu’élimine un moment unique : une Release qui se résout proprement alors qu’une entrée nécessaire à son rendu reste non épinglée, découverte seulement au moment du build.
--auto-pull intègre cette même résolution dans un build, et le build n’effectue qu’un seul rendu. Le rendu du remplissage est celui qui trouve et épingle les entrées externes, et le build présente ce rendu au lieu d’en effectuer un second, de sorte qu’un build en une seule commande coûte le même rendu qu’un build ordinaire sur un lockfile déjà rempli. aggrega build précise lesquels des flags de rendu d’un build l’atteignent.
L’ensemble découle des paramètres de la Release, ce qui est déjà le comportement des épingles de composants. Modifier les paramètres d’une Release entre la résolution et le build est une modification de la Release ; le build s’arrête donc à la comparaison de dérive en nommant le fichier, avant qu’un rendu ne puisse demander une URL non épinglée ; le remède est cette commande. Les paramètres importés d’un fichier séparé ne sont pas enregistrés par leur contenu ; modifier plutôt ce fichier atteint donc le rendu, qui s’arrête en nommant l’URL non épinglée — avec un remède qui nomme lui aussi cette commande.
Déterminisme et intégrité
La source: d’une Recipe peut définir sa version par template à partir des values et de l’infra résolus de la Release (et des locals définis sur ceux-ci) ; ils sont résolus au moment du pull et le résultat est épinglé. Le pull n’évalue que les entrées locals: que lisent les champs source:, ainsi que les entrées que celles-ci lisent à leur tour, avec les seuls helpers de template propres à Aggrega : une entrée lue par la source qui appelle une fonction Sprig arrête le pull en nommant l’entrée, le champ et la fonction, tandis qu’une entrée qu’aucun champ source: ne lit est laissée au build, qui l’évalue et la vérifie lors du rendu de la Recipe — voir Resolving a source: coordinate registers a narrower function set (La résolution d’une coordonnée source: enregistre un ensemble de fonctions plus restreint). Un tag ou une branche Git mutable est épinglé au commit concret vers lequel il pointe, et la ref que vous avez écrite est enregistrée à côté. Au moment du build, le digest de l’archive en cache est revérifié par rapport au lockfile, de sorte qu’un cache altéré est détecté.
Une ref enregistrée est tenue au commit qu’elle a épinglé. La ref est enregistrée parce que les exécutions ultérieures l’interrogent à nouveau, et non pour la lisibilité — un build demande quel artefact elle nomme, et un pull demande si elle pointe toujours au même endroit. Un pull qui n’est pas une mise à niveau demande à nouveau à chaque ref enregistrée où elle pointe, et une ref qui a bougé sur son dépôt distant arrête l’exécution — en nommant l’artefact, la ref, le commit qu’épingle le lockfile et le commit vers lequel elle se résout désormais — au lieu d’adopter le déplacement. Exécutez aggrega pull --upgrade --release <release> pour l’adopter. Une mise à niveau ciblée, qui nomme des URI d’entités, ne le fait pas : une référence de source n’est pas une entité que vous pouvez nommer, de sorte qu’une exécution ciblée la conserve exactement comme le fait un simple pull.
Cette vérification est la seule chose que la revérification du digest au moment du build ne peut pas faire pour vous. Un pull qui adopterait une ref déplacée réécrirait les octets récupérés et le digest enregistré dans le même acte, de sorte que les deux valeurs que compare un build auraient bougé ensemble et concorderaient — et vous effectueriez le build d’un contenu source différent de celui sur lequel le lockfile a été relu, sans que rien ne le signale.
Seule une ref que le lockfile enregistre est tenue de cette manière, et une ref est enregistrée chaque fois que vous en écrivez une. Une Recipe qui nomme sa source uniquement par version: n’a pas de ref, de sorte qu’il n’y a rien qu’une exécution ultérieure doive interroger à nouveau — ce qui est la bonne réponse, car une version que vous avez écrite vous-même ne peut pas bouger à votre insu. La référence du lockfile indique ce qui est enregistré.
Écrivez la ref, pas le commit. Un build trouve un artefact issu de git par la ref que vous avez écrite, mise en correspondance avec la ref que le lockfile a enregistrée, de sorte que ref: v1.2.3 effectue le build sur le commit auquel ce tag a été épinglé et que le commit n’a jamais besoin d’apparaître dans votre Recipe. Nommer plutôt un tag mutable dans version: ne fonctionne pas et n’est pas prévu pour fonctionner : version: est mis en correspondance tel qu’il est écrit, et pour une source git le lockfile épingle un commit.
Le lockfile épingle le contenu récupéré depuis les registres et les sources distantes, et enregistre le digest de chaque entité qu’il résout depuis vos répertoires de catalogue — sur le fichier de l’entité et chaque fichier qu’elle nomme à côté, comme le décrit Le lockfile — et de chaque fichier de Release que la résolution a lu. Les fichiers d’une source commençant par ./ ou ../, et un fichier d’artefact qu’importe une entité, sont aussi épinglés un par un dans le verrou à côté de cette entité, comme le décrit Le verrou d’entité, ce qui permet de nommer celui qui a bougé ; l’intégrité du reste de votre workspace entre les builds relève du système de gestion de versions. Voir sortie identique octet pour octet pour la portée de la garantie de déterminisme.
Authentification
Les identifiants de registry sont lus uniquement dans la configuration des identifiants Docker : config.json dans le répertoire que nomme DOCKER_CONFIG, ou ~/.docker/config.json lorsque cette variable n’est pas définie, ainsi que tout credential helper ou trousseau du système d’exploitation auquel le fichier délègue via credsStore ou credHelpers. aggrega login <registry> y écrit un identifiant, tout comme docker login <registry> ; exécutez l’un ou l’autre avant aggrega pull pour un catalogue OCI ou un registry de charts privé. Les fichiers qu’écrivent podman login et helm registry login ne sont pas lus.
Une configuration d’identifiants illisible est signalée sans ce qu’elle contient. Lorsque config.json n’est pas du JSON valide, que la valeur auth d’une entrée n’est pas un utilisateur et un mot de passe joints par deux-points et encodés en base64, ou qu’un credential helper nommé par le fichier ne peut pas répondre, l’accès au registre échoue avec un message qui nomme le registre et le fichier d’identifiants, jamais ce que contient le fichier ou l’entrée. aggrega login et aggrega logout signalent de la même manière un config.json qui n’est pas du JSON valide, et n’y modifient rien. Corrigez le fichier ; une entrée illisible peut aussi être remplacée avec aggrega login <registry>.
Un dépôt de charts Helm classique ou une archive de chart (helm-https-chart), un fragment compose (compose-https-fragment) et un dépôt Git atteint par HTTP ou HTTPS (git-repository) s’authentifient avec le fichier netrc, le fichier d’identifiants par utilisateur que lisent aussi curl et Git. C’est le seul magasin d’identifiants que lisent ces trois types : ~/.config/helm/repositories.yaml et les credential helpers de Git ne sont pas lus. Un dépôt Git atteint par SSH s’authentifie via l’agent SSH et ne lit aucun fichier netrc.
machine charts.example.com login deploy-bot password <token>Quel fichier est lu. Le fichier que nomme la variable d’environnement NETRC, lorsqu’elle est définie. Sinon .netrc dans votre répertoire personnel ; sous Windows, _netrc dans %USERPROFILE% lorsque ce fichier existe, et .netrc au même endroit sinon. Un fichier absent ne contient aucun identifiant et n’est pas une erreur. Un fichier qui existe et ne peut pas être lu, ou qui ne suit pas le format netrc, arrête la commande avec E0360, en nommant le fichier — et, pour une erreur de format, la ligne — mais jamais ce que contient le fichier : The netrc file cannot be read (Le fichier netrc ne peut pas être lu). Sous Linux et macOS, un fichier netrc que d’autres utilisateurs de la machine peuvent lire déclenche un avertissement qui le nomme ; rendez-le lisible par vous seul (chmod 600).
Quelle entrée répond à une requête. Chaque requête est recherchée par son hôte — le nom d’hôte sans le port, sans tenir compte de la casse — et reçoit sa réponse de la première entrée machine qui nomme cet hôte, ou de l’entrée default lorsqu’aucune ne le nomme. Le login et le password de l’entrée sont envoyés comme identifiants HTTP basic, en http comme en https ; une entrée à laquelle il manque l’un ou l’autre n’envoie rien. Un dépôt dont l’index place ses charts sur un autre hôte reçoit une réponse requête par requête : la requête de l’index prend l’entrée de l’hôte du dépôt, et la requête du chart celle de l’hôte du chart. Une requête envoyée sans identifiant doit être lisible anonymement, et un serveur qui répond 401 ou 403 arrête le pull comme une récupération non autorisée, dont le remède nomme l’entrée à ajouter et le fichier dans lequel elle a été cherchée.
L’identifiant n’est écrit nulle part. Il est lu lorsqu’une récupération s’exécute et envoyé avec la requête : le lockfile, l’entity.lock à côté de la Recipe, le cache des sources et chaque message portent l’URL de la source telle que vous l’avez écrite.
Une URL de source ne contient aucun identifiant. Une Recipe ou FeatureRecipe dont l’url de source écrit un utilisateur avant son hôte — https://user:token@charts.example.com/…, ou un jeton écrit seul comme https://token@charts.example.com/… — est refusée avec E0361 à la lecture du document, avant toute récupération : la validation de la Recipe la refuse, tout comme chaque pull, pin et build qui l’atteint. Le message nomme l’hôte et jamais l’identifiant : A source URL carries a credential (Une URL de source contient un identifiant). Placez plutôt l’identifiant dans une entrée machine du fichier netrc. En SSH, un utilisateur écrit seul — ssh://git@github.com/… — nomme un compte plutôt qu’un secret et est accepté, tandis qu’un mot de passe écrit à cet endroit est refusé lui aussi.
La vérification ne lit que la partie de l’URL qui précède l’hôte. Un jeton porté dans une chaîne de requête ou un chemin — …/index.yaml?access_token=… — n’est pas détecté, n’en écrivez donc pas à cet endroit : l’URL est enregistrée telle qu’écrite dans le lockfile, dans l’entity.lock et dans le cache des sources, noms des répertoires du cache compris.
Variables d’environnement
Les paramètres de workspace que pull lit peuvent être remplacés par l’environnement, au-dessus de la configuration commitée et en dessous de tout flag : AGGREGA_OFFLINE (voir Offline, et --offline pour le flag qui la prime), AGGREGA_CATALOG_DIRS (séparée comme une liste de chemins du système d’exploitation ; fournissez des chemins absolus), AGGREGA_ARTIFACT_CACHE_DIR, AGGREGA_DEFAULT_REGISTRY et AGGREGA_SKIP_SIGNATURE_VERIFICATION (bruyante — partout où un pull aurait vérifié une signature, il journalise un avertissement indiquant que la vérification est désactivée globalement). Voir environment-variables.md pour la liste complète et le modèle de priorité.
Voir aussi
- ./aggrega-build.md — vérifie le lockfile et effectue le pull automatiquement lorsque c’est configuré.
- ./aggrega-serve.md — le daemon propose cette même résolution sur
aggrega/resolveDependencies, et au sein deaggrega/buildpour une requête dont le champautoPullla demande, de sorte qu’un éditeur peut l’exécuter sans quitter la session ; dans les deux cas, elle ne s’exécute que lorsqu’une requête la nomme, et écrit le même lockfile que cette commande. - ./aggrega-push.md — publie des entités de catalogue dans un registre.
- ./aggrega-lint.md — le contrôle de publication qui précède
aggrega push. - ../../architecture/13-catalog-and-registry.md — le modèle complet du catalogue, du lockfile et du cache.
Synopsis
aggrega pull [<uri>...] [flags]Description
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.Options
| Option | Par défaut | Description |
|---|---|---|
--catalog | [] | Répertoire de catalogue ; répétable. Chaque —catalog <dir> est ajouté en tête de la pile de recherche du catalogue (la première correspondance l’emporte) : les catalog_dirs du workspace ou, pour une Release à laquelle la configuration du workspace attribue ses propres répertoires sous workspace.releases, ceux de cette Release ; la pile se termine par le répertoire nommé catalog à la racine du workspace lorsqu’il existe. Une liste catalog_dirs écrite vide ne lit aucun catalogue local. |
--detail | false | Affiche, pour chaque entité résolue, ce qu’a fait ce pull — récupérée à neuf depuis un registre, emplacement de cache réutilisé, trouvée dans un catalogue local, servie depuis l’intérieur du binaire du compilateur, ou externe (l’Aggregate ou le Manifest propre à la Release, lu depuis le fichier ou l’entrée que nomme la Release). Stdout uniquement ; non écrit dans le lockfile |
--dry-run | false | Résout les dépendances et affiche ce que ce pull écrirait au lieu de l’écrire : le chemin de chaque fichier et le contenu qu’il contiendrait vont sur stdout, et le lockfile, l’entity.lock à côté de chaque Recipe et FeatureRecipe dont les épingles enregistrées bougeraient sous —pin-sources, ainsi que l’enregistrement de confiance des plugins restent tous intacts. Seuls les fichiers qui changeraient réellement sont nommés. La résolution elle-même s’exécute exactement comme dans le cas contraire, de sorte que le cache de contenu se remplit tout de même, qu’un pull qui s’arrêterait sur une entité non épinglée s’arrête ici aussi, et qu’un —upgrade sans argument ne demande rien parce qu’il ne supprime aucune épingle — ce que montre une exécution à blanc est ce qu’un pull écrirait. Non accepté avec —verify, qui n’en écrit déjà aucun |
--include-prerelease | false | Pas encore implémenté : accepté et ignoré, de sorte qu’un script qui le passe continue de fonctionner lorsqu’il commencera à avoir un effet |
--pin-sources | false | Exécute l’étape d’épinglage de l’auteur de l’entité sur les Recipes et FeatureRecipes que cette Release construit, en enregistrant dans l’entity.lock à côté de chacune l’épingle de chaque entrée qu’elle lit — une source: distante écrite en entier, un fichier qu’importe une entrée artifacts et chaque fichier d’une source locale — au lieu de s’arrêter sur une entité dont le verrou ne les enregistre pas. La même étape que aggrega pin, qui écrit les mêmes octets. Elle écrit à côté de l’entité ; elle ne s’exécute donc que là où l’entité dispose d’un emplacement accessible en écriture : un document dans l’un de vos répertoires de catalogue. Une entité résolue depuis le cache n’en a pas et n’est jamais épinglée. Remplace le pin_sources_at_pull du workspace dans les deux sens : —pin-sources épingle pour cette exécution et —pin-sources=false s’arrête pour cette exécution, quoi qu’indique le paramètre |
--progress | false | Force l’affichage de la progression du pull même lorsque stderr n’est pas un terminal, en affichant une ligne simple par étape à mesure qu’elle se termine, avec sa durée. La valeur par défaut est auto : la liste de contrôle interactive des phases n’est affichée que lorsque stderr est un terminal qui interprète les séquences d’échappement, un terminal qui ne les interprète pas reçoit les mêmes lignes simples, et une sortie redirigée ou envoyée dans un pipe n’en reçoit aucune |
--quiet | false | Masque l’affichage de la progression du pull sur stderr. N’affecte pas stdout. Prévaut sur —progress |
--release | — | Chemin du fichier YAML de la Release (obligatoire). Un chemin relatif est résolu par rapport au répertoire dans lequel vous exécutez la commande, et non par rapport à la racine du workspace. Lorsque ce répertoire n’appartient à aucun workspace et qu’aucune racine n’est indiquée, un chemin absolu trouve le workspace à partir du dossier propre de la Release |
--upgrade | false | Résout à nouveau les dépendances à partir de l’état actuel des registres, en portant chacune à la version disponible la plus élevée. Sans argument (aucun URI positionnel), abandonne le lockfile et résout à nouveau chaque entité, et demande d’abord une confirmation parce qu’il supprime chaque épingle enregistrée ; avec un ou plusieurs URI d’entités, ne résout à nouveau que celles-ci, en conservant inchangées toutes les autres épingles et les entrées externes enregistrées, et ne demande rien (mutuellement exclusif avec —verify) |
--verify | false | Vérifie le lockfile existant par rapport à la résolution des dépendances qu’effectuerait un pull maintenant, sans écrire le lockfile, l’enregistrement de confiance des plugins ni aucun entity.lock ; se termine avec un code non nul en cas de dérive ou de lockfile absent. La résolution respecte les épingles qu’enregistre le lockfile exactement comme un pull : une référence dont le registre a publié une version plus récente depuis le pull n’est pas une dérive, car un pull conserverait son épingle, et un registre qui sert désormais des octets différents sous une version épinglée arrête la vérification comme il arrête un pull. Le cache de contenu est lu et rempli comme un pull le lit et le remplit : une entrée que le cache détient sous son épingle y est lue sans interroger de registre, une entrée qu’il ne détient pas est récupérée, et une entrée qui ne correspond plus à son épingle est traitée exactement comme un pull la traite. Confronte aussi l’entity.lock à côté de chaque Recipe et FeatureRecipe de vos répertoires de catalogue qu’atteint la Release à ce à quoi un build la compare, et se termine avec un code non nul sur une épingle qu’un build refuserait : un fichier importé qui ne correspond plus à son digest enregistré, une source locale dont les fichiers ne correspondent plus à leurs digests enregistrés, ou une épingle de source en désaccord avec le lockfile. Compare aussi la signature qu’enregistre le lockfile pour chaque artefact, et l’enregistrement de confiance des plugins pour chaque plugin, avec celle qu’un pull enregistrerait maintenant, et se termine avec un code non nul là où un pull en enregistrerait, en remplacerait ou en effacerait une : une signature exigée par une condition requise qui n’est pas enregistrée, et une signature faite pour un autre artefact, sont signalées sans interroger de registre, car un pull les réécrit quelle que soit sa réponse ; une signature qu’un pull recherche à nouveau et pourrait enregistrer inchangée — l’artefact a été récupéré, ou son bundle de signature en cache a été supprimé ou altéré — est demandée à son registre, ou, en mode hors ligne, laissée non vérifiée avec une ligne l’indiquant ; et chaque plugin que couvre l’enregistrement de confiance des plugins est vérifié auprès de son registre, comme chaque pull le vérifie, sauf en mode hors ligne, où il est lu depuis le cache de contenu comme un build le lit, son identité et ses fonctions hôtes sont tout de même vérifiées, et sa signature est laissée non vérifiée avec une ligne l’indiquant, à moins qu’un build ne le refuse parce qu’aucune signature n’est enregistrée ou que celle enregistrée a été faite pour un autre artefact, ce qui est signalé. Les marqueurs de dépréciation ne sont pas comparés. Signale aussi les versions du compilateur et des plugins de base qu’enregistre le lockfile — signalées à des fins d’audit et jamais comparées à ce binaire, de sorte qu’une différence de chaîne d’outils n’est jamais une dérive. Non accepté avec —pin-sources, quelle que soit la valeur donnée : une vérification n’enregistre pas une épingle manquante dans un entity.lock et ne s’arrête pas non plus sur celle-ci, de sorte que le flag ne changerait rien (mutuellement exclusif avec —upgrade) |
--yes | false | Répond à l’avance à la confirmation du —upgrade sans argument, pour une utilisation non interactive. Il n’atteint que cette invite et rien d’autre : toute autre forme de pull ne demande rien, de sorte que le passer n’y change aucun comportement |