Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

aggrega pull

aggrega pull rozwiązuje wszystkie zależności encji Release i zapisuje plik blokady (lockfile), który przypina każdą zależność do dokładnej wersji i skrótu zawartości. Kolejne wywołanie aggrega build używa tego, co przypina plik blokady, weryfikuje to i zatrzymuje się, wskazując wszystko, czego potrzebuje, a co nie jest w nim przypięte — dzięki temu kompilacje są powtarzalne i mogą działać bez dostępu do sieci.

Wszystko, z czego korzysta kompilacja, zostaje przypięte w tym jednym momencie. Encje katalogu, artefakty źródłowe, na które encja Recipe kieruje dostawcę, oraz zdalne dokumenty, o które dostawca prosi podczas renderowania, są rozwiązywane przez to samo polecenie i zapisywane w tym samym zapisie pliku blokady. aggrega pull to krok, który korzysta z sieci; kompilacja z niej nie korzysta. Na tym polega cała reguła, a reszta tej strony opisuje jej konsekwencje.

Działanie

aggrega pull rozwiązuje trzy rodzaje zależności w jednym przebiegu:

  • Encje katalogu — encje Components, Features, Recipes, FeatureRecipes, biblioteki schematów i mapowań oraz pluginy Wasm, do których odwołuje się encja Release, rozwiązywane przechodnio (przez extends:, implements:, aggregate:, dołączenia encji Feature oraz miejsca $import: / $ref: w bibliotekach) i pobierane z rejestru, jeśli nie są jeszcze dostępne lokalnie.
  • Artefakty źródłowe — zdalne source:, na które pojedyncza encja Recipe lub FeatureRecipe kieruje providera: chart Helm (OCI lub klasyczny HTTPS) albo fragment Compose przez HTTPS. Każdy z nich jest pobierany, zapisywany w pamięci podręcznej i przypinany.
  • Wejścia zewnętrzne — zdalne dokumenty, o które provider prosi hosta podczas renderowania, np. $ref w pliku values.schema.json chartu wskazujący na adres URL. Każde z nich jest pobierane, przechowywane pod swoim skrótem treści i przypinane.

Dwa z tych trzech rodzajów są odczytywane z dokumentów napisanych przez autora. Trzeci nie: wejścia zewnętrzne są znajdowane przez wyrenderowanie encji Release, dlatego to polecenie ją renderuje. Do uruchomienia polecenia nic z tego nie jest potrzebne — sekcja Jak rozwiązywanie znajduje wejścia zewnętrzne opisuje to w całości, wraz z kosztem renderowania, tym, co się dzieje, gdy nie może się ono zakończyć, oraz związkiem z kompilacją, która sama wypełnia swój plik blokady.

Encja katalogu wskazana bez rejestru jest pobierana przez default_registry obszaru roboczego, a ścieżka repozytorium zawarta w tej wartości domyślnej określa, skąd jest pobierana. Przy default_registry: ghcr.io/acme encja core/api-server jest pobierana z ghcr.io/acme/component/core/api-server — gdzie aggrega push publikuje ją przez tę samą wartość domyślną — i tam też szukany jest jej podpis. Ścieżka określa wyłącznie lokalizację: podpis wymagany przy pobieraniu, zaufane klucze i tożsamości oraz przedstawiane poświadczenie są tymi zapisanymi dla hosta, więc wpis registries dla ghcr.io obejmuje każdą ścieżkę na tym hoście. Plik blokady zapisuje taką encję przez jej tożsamość, wersję i skróty, tak samo jak encję pobraną z samego hosta. Zapis ścieżki opisano w sekcji jak zapisuje się host rejestru.

Wynik jest zapisywany do <release-stem>.lock obok encji Release. Obszar roboczy, który dołącza plugin zwracający werdykt akceptacji lub odrzucenia, otrzymuje w tym katalogu także drugi plik — rejestr zaufania pluginów.

Pobieranie z żądaniem przypięcia zapisuje jeszcze jeden rodzaj pliku. Obok każdej encji Recipe i FeatureRecipe w katalogach katalogu, która importuje plik artefaktu, wskazuje na zdalne source: zapisane w pełnej postaci lub odczytuje source: leżące obok niej, znajduje się entity.lock zapisujący skrót tej treści. Zapisanie go jest krokiem autora encji, aggrega pin, i domyślnie pobieranie go nie wykonuje: sprawdza blokadę każdej takiej encji względem tego, co zapisałby ten krok, i zatrzymuje się tam, gdzie brakuje przypięcia. aggrega pull --pin-sources lub obszar roboczy ustawiający pin_sources_at_pull: true wykonuje ten krok zamiast tego — wtedy skutki pobierania sięgają poza katalog, w którym leży encja Release, choć napisane przez autora pliki encji nigdy nie są nadpisywane. Sekcja Blokada encji opisuje ten plik, a Podgląd tego, co zapisałoby pobieranie pokazuje cały ich zestaw dla obszaru roboczego, zanim cokolwiek się zmieni.

Pobieranie odrzucone, ponieważ odwołanie nie zostało rozwiązane do niczego, informuje, skąd odczytywane są encje lokalne, niezależnie od miejsca uruchomienia. Odmowa zawiera opis obszaru roboczego dotyczący katalogów, z których odczytał encje lokalne, oraz tego, co zmienić, aby encja została odczytana — jak pokazuje uwaga Skąd odczytywane są encje lokalne — i zawiera go zarówno przy tym poleceniu, jak i przy kompilacji, która najpierw rozwiązuje swoje zależności, przy narzędziu pull w aggrega mcp oraz przy rozwiązywaniu zależności w edytorze, ponieważ składa go wspólny dla nich wszystkich mechanizm rozwiązywania. Odmowa narzędzia pull podaje też krótki kod warunku i jego kod opisowy, tak jak terminal wypisuje krótki kod na początku odmowy. Plik w tych katalogach, który deklaruje apiVersion Aggrega — wiersz zaczynający się bez wcięcia od apiVersion: i wartości rozpoczynającej się od aggrega.ai/ — a którego nie udało się wczytać, na przykład taki, który nie parsuje się jako YAML, jest wymieniony w tej samej odmowie, wśród plików katalogu pominiętych przy wczytywaniu, wraz z powodem podanym przez sam parser: taki plik może być tym, który deklaruje encję wskazaną przez odwołanie, a nie da się z niego odczytać niczego, co powiedziałoby, jaką encję deklaruje. Plik YAML deklarujący inną apiVersion albo żadnej nie jest dokumentem Aggrega i nigdy nie jest tam wymieniany.

Plik blokady

Plik blokady przypina każdą zależność do jej URI, rozwiązanej wersji i skrótu treści. Zawiera sekcje dla encji katalogu, bibliotek schematów i mapowań (każda z odwołaniami zwrotnymi do encji Components i Features, które z niej korzystają), wtyczek Wasm, artefaktów źródłowych, wejść zewnętrznych (każde z kluczem w postaci URL i z listą wtyczek, które o nie poprosiły) oraz samych plików encji Release. Plik jest zapisywany w kanonicznej, deterministycznej postaci.

Encja jest rejestrowana według tego, co zawiera jej publikacja. Skrót w wierszu encji obejmuje jej dokument i każdy plik, który ona wskazuje obok siebie — lokalne source: encji Recipe lub FeatureRecipe, każdy plik wskazany przez $import:, leżący obok niej entity.lock, każdy plik schematu importowany przez encję Component lub Feature — czyli ten sam zestaw, który publikuje aggrega push. Każdy plik wnosi swoją ścieżkę i swoje bajty i nic poza tym: ani sposób kompresji archiwum, ani znacznik czasu, ani bit uprawnień, łącznie z bitem wykonywania. Encja, która nie wskazuje żadnego pliku, jest rejestrowana jako ten jeden dokument. Dzięki temu ta sama encja ma ten sam skrót niezależnie od tego, czy odczytano ją z katalogu lokalnego, czy pobrano z rejestru, a plik blokady zatwierdzony z jednej kopii roboczej weryfikuje się w innej kopii tego samego commita bez względu na jej umask i na to, czy system tej kopii rejestruje, które pliki są wykonywalne. Wykres zmieniony w encji Recipe, plik dodany do deklarowanego przez nią źródła i zmieniony entity.lock zmieniają skrót; skrypt, któremu zmienił się bit wykonywania, ani notatka obok encji, której nic nie wskazuje — nie. Encje Aggregate i Manifest wskazane przez Release są rejestrowane tak samo, każda jako swój jeden dokument. Biblioteka jest rejestrowana według skrótu swoich bajtów, którymi jest jej dokument niezależnie od miejsca, z którego go odczytano.

Każda encja Recipe i FeatureRecipe wiązana przez Manifest jest wierszem, niezależnie od poziomu, który ją wiąże. Realizacja wybrana przez poziom name encji Manifest dla jednej instancji lub jednego dołączenia jest pozyskiwana i rejestrowana dokładnie tak jak realizacja wybrana przez poziom type dla każdej instancji typu, a pole referenced_from jej wiersza wskazuje wiążący ją wpis — manifest.spec.mappings.components.name.<instance> lub manifest.spec.mappings.features.name.<attachment>. Kompilacja trzyma ją przy tym wierszu, więc plik blokady, który jej nie rejestruje, zatrzymuje kompilację ze wskazaniem realizacji i tego wpisu. Oba poziomy opisuje Płaskie mapowanie URI.

Dołączenia połączenia są zależnościami dokładnie tak jak dołączenia samego komponentu. Encja Feature wskazana przez dołączenie na połączeniu — zapisane we wpisie uses: komponentu w encji Aggregate lub we wpisie połączenia w encji Release — jest pozyskiwana i rejestrowana jak encja Feature dołączenia zapisanego na samym komponencie, a pole referenced_from jej wiersza wskazuje wpis połączenia zapisany przez autora, zakończony .uses.<socket>.<alias>.features.<slot>.type. Realizacja wiązana z nią przez Manifest również jest wierszem, niezależnie od tego, czy wiąże ją features.type, czy features.name z kluczem w postaci nazwy dołączenia, <alias>.<slot>. Kompilacja trzyma obie przy ich wierszach: plik blokady bez jednej z nich zatrzymuje kompilację ze wskazaniem odwołania i wpisu, który o nie prosi, a encja Feature, której treść zmieniła się od pobrania, zatrzymuje ją ze wskazaniem obu skrótów. Samo dołączenie opisuje wpis połączenia w encji Aggregate.

Baza, którą rozszerza encja Component lub Feature, jest wierszem niezależnie od tego, czy wskazuje ją cokolwiek innego. Operacja pull podąża za każdym extends: do końca łańcucha i zapisuje każdą bazę pod jej własnym rodzajem, a referenced_from jej wiersza wskazuje spec.extends encji rozszerzającej — component(<name>:<version>).spec.extends. Kompilacja odczytuje bazę z tego wiersza, więc encja Manifest mapuje własny typ encji opakowującej i nie potrzebuje wiersza dla jej bazy. Baza, której nie zawiera żaden katalog encji katalogowych, pamięć podręczna ani rejestr, jest zgłaszana w miejscu scalania łańcucha — zob. An extends: chain cannot be assembled (Nie można złożyć łańcucha).

Encja Release jest rejestrowana według treści, nie tylko według nazwy. Wszystko, o co prosi Release — do której wersji wykresu rozwiązuje się źródło, które komponenty trafiają do której granicy — wynika z zawartości pliku, dlatego release_documents rejestruje skrót encji Release i każdej encji Release, którą ona rozszerza, obok pola release, które ją nazywa. Edycja encji Release po pobraniu sprawia, że następna kompilacja zatrzymuje się przed renderowaniem, wskazując edytowany plik i polecając ponowne pobranie; zwykłe aggrega pull --release <release> rejestruje zmianę, respektując wszystkie pozostałe przypięcia. Skrót obejmuje bajty pliku w obecnej postaci, więc zmiana komentarza lub białych znaków również się liczy, dokładnie tak jak w przypadku encji Aggregate i Manifest. Plik importowany przez Release poprzez parameters nie jest rejestrowany w ten sposób.

Pobieranie szuka znacznika wycofania na każdym artefakcie, którego podpis sprawdza, i informuje, co znalazło. Znacznik, którego własny podpis weryfikuje się względem podpisującego honorowanego przez pobieranie — podpisującego sam artefakt lub tożsamości z trusted_deprecation_identities rejestru — jest rejestrowany i ogłaszany wraz z poziomem ważności i podpisującym znacznik. Znacznik, który pobieranie znalazło, ale nie mogło honorować — nieczytelny, niepodpisany, podpisany przez kogoś, komu polityka nie ufa, lub opatrzony podpisem, którego nie dało się sprawdzić — jest zgłaszany jako marker present but not honored wraz z powodem i nie jest rejestrowany. Wyszukiwanie, którego nie dało się dokończyć — pobieranie nie mogło otworzyć rejestru artefaktu albo lista tego, co jest do niego dołączone, nie odpowiedziała — jest zgłaszane jako marker lookup did not complete wraz z powodem i niczego nie rejestruje, ponieważ pobieranie nie dowiedziało się niczego o tym, czy znacznik istnieje. W rejestrze, którego własna polityka zaufania wymaga podpisu dla rodzaju artefaktu i nie jest advisory, każdy z tych dwóch przypadków zatrzymuje pobieranie, zamiast zostać zgłoszony. Artefakt bez znacznika nie daje żadnego wiersza, a tam, gdzie weryfikacja podpisów jest wyłączona — dla obszaru roboczego lub dla rejestru artefaktu — znacznik nie jest wyszukiwany.

Plik <release-stem>.lock należy zatwierdzać razem z encją Release, tak jak każdy manifest przypiętych zależności. Diff pliku blokady pokazuje recenzentom dokładnie, które wersje i skróty zależności się zmieniły; zmiana skrótu biblioteki wskazuje konsumentów, na których wpływa.

To, co dane pobranie zrobiło — czy każda encja została świeżo pobrana z rejestru (fetched-fresh), użyła ponownie miejsca w pamięci podręcznej (cache-reuse), została znaleziona w katalogu lokalnym (local), dostarczona z kopii wewnątrz pliku binarnego kompilatora (in-binary), czy była zewnętrzna (external: własne encje Aggregate lub Manifest danej encji Release, odczytane z pliku lub wpisu wskazanego przez Release, a nie rozwiązane jako jedna z jej zależności; encja Aggregate pobrana przez pull z rejestru ma zamiast tego fetched-fresh) — jest przejściową diagnostyką zdarzeń pobrania, wypisywaną na stdout przez --detail, i nigdy nie trafia do pliku blokady. To, które źródło dostarczyło encję, zależy od stanu lokalnego maszyny wykonującej pobranie, więc utrwalenie tego zniszczyłoby bajtową identyczność pliku blokady między maszynami. Raportuje to, co zrobiło to pobranie, czego nie da się później odtworzyć (świeżo pobrana encja jest przy następnym uruchomieniu w pamięci podręcznej); do sprawdzenia stanu rozwiązania zależności encji Release po pobraniu służy aggrega inspect.

Blokada encji

Encja Recipe lub FeatureRecipe może zależeć od bajtów spoza własnego dokumentu: od wykresu lub fragmentu pobranego ze zdalnego source:, od pliku, który wpis artifacts — lub wpis boundary.artifacts encji Recipe — wprowadza przez $import, albo od plików source:, który wskazuje katalog lub plik obok niej. Skrót, jaki dało każde z tych wejść, jest zapisywany w pliku o nazwie entity.lock, w tym samym katalogu co plik encji. Do pliku encji napisanego przez autora nic nie jest nigdy zapisywane; to, co z niego wyprowadzono, leży obok. Schemat blokady encji opisuje ten plik pole po polu.

Kto go zapisuje. Zapisuje go jeden krok: aggrega pin, który uruchamia autor encji, który nie wymaga encji Release i który zapisuje każdą klasę przypięć przechowywanych w blokadzie. aggrega pull --pin-sources i aggrega push --pin-sources uruchamiają ten sam krok w imieniu autora i zapisują te same bajty. Pull, którego nie poproszono o przypinanie, nie zapisuje żadnej blokady: dla każdej encji Recipe i FeatureRecipe, z których Release buduje z katalogów katalogu, porównuje to, co zapisałby krok, z tym, co zawiera blokada, i zatrzymuje się tam, gdzie brakuje przypięcia lub przestało ono odpowiadać swojemu wejściu, podając encję, każde wejście i jego klasę oraz aggrega pin. Pliki lokalnego źródła są porównywane ze swoimi przypięciami jako jeden zbiór: blokada, która nie zapisuje żadnego z nich, zatrzymuje pull, podobnie jak plik dodany, zmieniony lub usunięty od czasu przypięcia. Klucz przestrzeni roboczej pin_sources_at_pull czyni przypinanie domyślnym zachowaniem każdego pull, a --pin-sources=false przywraca zatrzymanie na jedno uruchomienie. Przypinanie jest obowiązkiem autora, więc zatrzymanie przy pierwszym pull konsumenta oznacza, że wydawca encji nigdy jej nie przypiął; rozwiązaniem dla konsumenta jest ten klucz, a nie ręczna edycja cudzego katalogu. aggrega pin opisuje to w całości.

Co zawiera. Trzy listy, a każdy wiersz wskazuje jedno wejście:

  • sourceDigests — jeden wiersz dla każdego zdalnego source:, którego współrzędne zapisano w całości, bez szablonu w kind, url, chart, module_subdir, version ani ref. Wiersz zawiera kind i url źródła, jego chart lub module_subdir, jeśli je ma, wersję, na którą zostało rozwiązane — dla źródła git commit wskazany przez jego ref — oraz skrót zawartości pobranego archiwum, a także skrót manifestu dla wykresu pobranego przez OCI.
  • artifactDigests — jeden wiersz dla każdego wpisu artifacts lub boundary.artifacts dostarczanego przez plik zaimportowany przez $import, wskazujący wpis i skrót bajtów pliku. Wpis artifacts jest wskazywany przez swój klucz, a wpis boundary.artifacts jako boundary/<key>, więc wpisy obu bloków zapisane pod jednym kluczem są przypinane osobno.
  • localSourceDigests — jeden wiersz dla każdego pliku, który source: wskazujący katalog lub plik obok encji wnosi do tego, co zawiera publikacja encji, wskazujący ścieżkę pliku obok encji i skrót jego bajtów. Dla takiego źródła nic nie jest pobierane; jego pliki są skracane w obecnej postaci. Źródło zapisane jako szablon wnosi każdy plik w katalogu encji, więc każdy z nich ma wiersz.

Czego nie zawiera:

  • Zdalnego źródła, którego współrzędne są uzupełniane z szablonu — na przykład version odczytanego z .infra. To, który artefakt wskazuje, rozstrzyga każda encja Release używająca tej encji, więc każda wersja, na którą zostanie rozwiązane, jest przypinana w pliku blokady tej encji Release i nic na jego temat nie jest zapisywane obok encji.
  • Wpisu artifacts lub boundary.artifacts zapisanego inline, który jest częścią pliku encji, ani wpisu pobranego z ArtifactLibrary, którego zawartość przypina wersja biblioteki zapisana w pliku blokady.

Encja, której nie ma czego przypinać, nie otrzymuje entity.lock, a krok uruchomiony dla encji, która już go nie potrzebuje, usuwa go.

Należy go zatwierdzić obok encji. Każda encja Recipe i FeatureRecipe używa tej samej nazwy pliku, a katalog, w którym leży, wskazuje, do której encji należy, więc blokada przemieszcza się razem z tym katalogiem. Nie zawiera znacznika czasu, a jej wiersze są utrzymywane w stałej kolejności, więc krok wykonany na niezmienionych wejściach pozostawia ją identyczną co do bajtu, a diff wskazuje źródło, zaimportowany plik lub plik lokalnego źródła, który się zmienił. Katalog zawiera jedną blokadę, więc krok odrzuca encję Recipe lub FeatureRecipe, obok której leży inna encja — każdy rodzaj ma własny katalog z wyjątkiem Aggregate, Release i Manifest — a pull poproszony o przypinanie odrzuca taką encję, zanim cokolwiek zostanie rozwiązane; Jedna encja na katalog opisuje tę regułę. Pull, który nie przypina, nie zapisuje niczego obok encji i nie ocenia jej katalogu.

aggrega build porównuje z nim pliki. Build odczytuje blokadę i wykonuje trzy porównania:

  • Każdy zaimportowany plik jest ponownie skracany i porównywany ze swoim wierszem, plik boundary.artifacts dokładnie tak jak plik artifacts. Plik edytowany po przypięciu zatrzymuje build z [CATALOG_ERROR E0026], podając artefakt tak, jak nazywa go wiersz, zaimportowany plik i oba skróty.
  • Pliki lokalnego źródła są ponownie skracane i porównywane ze swoimi wierszami jako jeden zbiór, zanim provider odczyta źródło. Plik edytowany, dodany lub usunięty od czasu przypięcia zatrzymuje build z E0305 pod instancją komponentu, do której należy źródło, podając każdy taki plik i oba skróty; plik obok encji, którego źródło nie wnosi, nie jest porównywany. Blokada, która nie zapisuje żadnego wiersza dla lokalnego źródła, nie pozostawia niczego do porównania, jak opisuje A local source no longer matches the pins recorded beside its Recipe (Lokalne źródło nie odpowiada już przypięciom zapisanym obok jego Recipe).
  • Każdy wiersz źródła jest porównywany ze skrótem, który plik blokady encji Release zapisuje dla tego samego źródła. Niezgodność zatrzymuje build z [FETCH_ERROR E0135], podając blokadę i oba skróty. Oba pliki są zapisywane przez dwa rozwiązania tego samego źródła — kroku przypinania i pull — więc są niezgodne, gdy te rozwiązania otrzymały różne bajty lub gdy jeden z plików został edytowany. Różne bajty pod jedną wersją oznaczają, że źródło upstream ponownie opublikowało wersję.

Plik blokady zapisany przed zmianą zatrzymuje build jako pierwszy, a pull wskazuje plik. Plik blokady zapisuje encję według tego, co zawiera, a blokada i każdy plik odczytywany przez te porównania są tego częścią, więc build — lub aggrega pull --verify — z plikiem blokady zapisanym przed zmianą zaimportowanego pliku, pliku lokalnego źródła lub samej blokady zatrzymuje się, zanim zostanie wykonane którekolwiek z trzech porównań: The lockfile no longer matches what the release resolves to (Plik blokady nie odpowiada już temu, na co rozwiązuje się release), podając encję i oba skróty. Zwykły aggrega pull wskazuje wtedy plik, ponieważ porównuje blokadę z tym, co zapisałby krok przypinania, i odrzuca wejście, którego przypięcie już nie odpowiada: An entity reads an input the lock beside it records no pin for (Encja odczytuje wejście, dla którego blokada obok niej nie zapisuje przypięcia).

Tam, gdzie plik blokady nie zapisuje własnej zawartości encji, build napotyka trzy porównania. Encja Recipe lub FeatureRecipe, którą Manifest wskazuje przez odwołanie będące zarazem nazwą encji Component lub Feature osiąganej przez Release, nie ma własnego wpisu: wpis pliku blokady dla tego odwołania zapisuje Component lub Feature, więc nic w pliku blokady się nie zmienia, gdy zmieniają się pliki encji Recipe, a build i pull weryfikujący zgłaszają zmieniony plik z powyższym kodem. Porównanie wiersza źródła jest również tym, co napotyka build, gdy wpis source_artifacts pliku blokady jest zapisem, który się zmienił, podczas gdy blokada obok encji pozostała bez zmian.

Reagowanie na zatrzymanie. Jeśli zaimportowany plik został zmieniony celowo, należy uruchomić aggrega pin dla encji: krok zapisuje nowy skrót pliku, a następna kompilacja go akceptuje. W przeciwnym razie należy przywrócić plik. Dla źródła lokalnego, które się zmieniło, są te same dwie odpowiedzi: ponowne przypięcie encji albo przywrócenie plików wskazanych przez zatrzymanie. Dla wiersza źródła niezgodnego z plikiem blokady należy przywrócić entity.lock z systemu kontroli wersji albo uruchomić aggrega pin dla encji, aby go przepisać.

aggrega pull --verify również to sprawdza. Pull weryfikujący wykonuje te same trzy porównania dla blokad obok encji Recipes i FeatureRecipes, do których Release dociera w katalogach użytkownika, zgłasza każde przypięcie, które kompilacja by odrzuciła, z tym samym kodem i tymi samymi słowami, kończy się kodem niezerowym, jeśli takie istnieje, i nie zapisuje żadnej blokady.

Gdzie żadna blokada nie jest porównywana. Encja Recipe lub FeatureRecipe rozwiązana z rejestru, a nie z jednego z katalogów użytkownika, nie ma blokady odczytywanej przez kompilację; jej źródła są sprawdzane wyłącznie względem pliku blokady encji Release. Ponadto źródło zapisane z git ref: jest zapisywane w blokadzie jako commit, na który ten ref został rozwiązany, podczas gdy kompilacja szuka przypięcia źródła w wersji wskazanej przez encję, więc ten wiersz nigdy nie jest porównywany — ani przez kompilację, ani przez pull weryfikujący. Plik blokady nadal przypina commit, a każda kompilacja weryfikuje względem niego archiwum w pamięci podręcznej.

Rejestr zaufania do pluginów

Niektóre pluginy dołączane przez przestrzeń roboczą nigdy nie kształtują renderowanego wyniku. Dołączenie plugins.governance w roli ir-verdict lub render-verdict oraz każde dołączenie plugins.linter zwracają werdykt akceptacji lub odrzucenia i nic więcej — żadne ich bajty nie trafiają do artefaktu. Nie należą więc do tego, co build odtwarza bajt po bajcie, a plik blokady, który przypina właśnie to, jest dla nich niewłaściwym miejscem.

Ich tożsamości trafiają zamiast tego do drugiego commitowanego pliku: plugins-trust.yaml, obok pliku blokady. Zawiera on jeden wpis na każdy taki plugin, zapisujący współrzędną tożsamości pluginu, wybraną dla niego wersję i skrót zawartości rozwiązanego artefaktu — a także podpis zweryfikowany przez pull dla tego artefaktu, jeśli jakiś zweryfikował, oraz, gdy wydawca od czasu publikacji oznaczył ten artefakt jako przestarzały, znacznik znaleziony i zweryfikowany przez pull. Schemat rejestru zaufania do pluginów opisuje plik pole po polu.

Plik plugins-trust.yaml należy commitować razem z plikiem blokady, z tego samego powodu, dla którego commituje się plik blokady: rejestru przechowywanego poza kontrolą wersji nikt nie może przejrzeć i nie można z nim niczego porównać. Zacommitowany jest jednym wspólnym stwierdzeniem, do którego pluginu rozwiązało się każde z tych dołączeń, a diff na nim wskazuje tożsamość, która się zmieniła.

Plik pojawia się tylko wtedy, gdy jest coś do zapisania. Przestrzeń robocza, która nie dołącza żadnego pluginu zwracającego werdykt, nie rozwiązuje żadnej takiej tożsamości, więc pull nie zapisuje pliku i nic o nim nie mówi — to brak, a nie brakujący plik. Gdy pull go tworzy, podaje nazwę utworzonego pliku i informuje, że należy go zacommitować. Późniejszy pull dodaje tożsamość, której rejestr jeszcze nie zawiera, a każdą już zapisaną tożsamość pozostawia dokładnie bez zmian.

Każda zmiana tego pliku jest ogłaszana i nic poza nią. Pull, który zmienia rejestr, wypisuje jeden wiersz na każdy zmieniony wpis, podając plugin i rodzaj zmiany: tożsamość zapisana po raz pierwszy, tożsamość przyjęta w miejsce dotychczasowej (z podaniem obu, aby było widać, co zostało podmienione), oznaczenie przestarzałości zapisane dla artefaktu, który wpis już wskazuje, oznaczenie przestarzałości usunięte z wpisu, podpis zapisany dla wpisu lub z niego usunięty albo usunięcie wpisu. Opisany wyżej wiersz o utworzeniu jest osobny i dotyczy pliku, a nie wpisu, więc pierwsze rozwiązanie mówi oba: ten plik jest nowy i należy go zacommitować, a to są tożsamości, które teraz zawiera.

Pull, który pozostawia rejestr dokładnie takim, jaki był, nic o nim nie mówi. Wiersz dotyczący tego pliku oznacza więc, że zacommitowany plik się zmienił i warto przeczytać jego diff — co ma tu większe znaczenie niż w przypadku pliku blokady. Wszystko, co przypina plik blokady, należy też do tego, co build odtwarza bajt po bajcie, więc zmiana w nim ma drugie miejsce, w którym się ujawni; tożsamość pluginu werdyktu nie ma żadnego. Ten plik jest jedynym miejscem, w którym zapisana jest podmiana bramki.

aggrega pull --dry-run nie ogłasza niczego z tego, ponieważ niczego nie zmienia. Zamiast tego wymienia rejestr wśród plików, które by zapisał, jak opisuje Podgląd tego, co zapisałby pull.

Oznaczenie przestarzałości jest dodawane do wpisu, który rejestr już zawiera, i nie jest tym samym co jego przepisanie. Jeśli wydawca oznaczy jako przestarzały plugin, któremu już się ufa, następne aggrega pull zapisuje znacznik w istniejącym wpisie tego pluginu — współrzędna, wersja i skrót pozostają nietknięte, ponieważ artefakt się nie zmienił i nic nowego nie jest przyjmowane. Zwykły pull może więc dodać blok deprecation, a tożsamość zmienia wyłącznie jawna aktualizacja. Znacznik jest zapisywany tylko dla artefaktu, który wpis już wskazuje, i żaden pull nie śledzi znacznika, który przestał być publikowany: zapisany znacznik znika tylko razem z wpisem, który go zawierał, czyli albo gdy ten wpis zostanie usunięty, albo gdy jawna aktualizacja ponownie rozwiąże plugin i nie znajdzie znacznika dla bajtów, które wpis już zapisuje.

Zweryfikowany podpis jest zapisywany we wpisie w ten sam sposób, a każdy pull ustala go od nowa. Pull przy każdym uruchomieniu weryfikuje podpis każdego z tych pluginów względem polityki zaufania jego rejestru — plugin serwowany przez rejestr jest za każdym razem pobierany według wersji, ponieważ nic go nie przypina — i zapisuje to, co zweryfikował, we wpisie pluginu, znów bez naruszania tożsamości: tryb, pasującego sygnatariusza i skrót zbuforowanego pakietu podpisu, ten sam signature, który zawiera wpis pliku blokady. W odróżnieniu od znacznika wynik zastępuje to, co zawierał wpis, a gdy pull nie zweryfikował żadnego podpisu — plugin go nie ma i nie jest on wymagany albo plugin został dopuszczony przez skip_signature_verification lub rejestr advisory — wpis nie zapisuje żadnego. Zweryfikowany pakiet podpisu jest również ponownie buforowany, a kopia w pamięci podręcznej, która nie odpowiada już swojemu skrótowi, jest przepisywana. Wpis, który utracił podpis, wpis z podpisem skopiowanym z innego pluginu, wpis, którego zbuforowany pakiet podpisu usunięto lub zmieniono, albo rejestr usunięty lub zapisany przed zapisaniem podpisu zostaje więc naprawiony przez następne zwykłe aggrega pull. Build rozlicza każdy taki plugin z tego faktu: zob. Rejestr zaufania do pluginów na stronie builda.

Rozwiązana tożsamość niezgodna z zapisaną zatrzymuje pull. Zapisany wpis podaje zarówno wersję, jak i skrót, więc zmiana któregokolwiek z nich jest tym samym zdarzeniem: plugin, który zostałby uruchomiony, nie jest pluginem, dla którego przejrzano rejestr. Komunikat diagnostyczny podaje plugin, zawartość rejestru i wynik tego rozwiązania, w obu osiach naraz — a pull zatrzymuje się bez naruszania rejestru, więc przejrzana tożsamość pozostaje do porównania. Zatrzymuje się na samej wersji (ponowna publikacja z niezmienionymi bajtami) dokładnie tak, jak na samym skrócie (ponowne wypchnięcie w tej samej wersji).

aggrega pull --verify wykonuje to samo porównanie. Nie zapisuje żadnego z plików, które commituje pull, więc niczego nie przyjmuje; raportuje, czy te pliki nadal opisują to, co pull rozwiązałby dziś, a rejestr jest jednym z nich. Porównuje też podpis każdego wpisu z tym, który daje własna weryfikacja pluginu przez pull, i raportuje wpis, którego podpis pull by zapisał, zastąpił lub usunął — oraz plugin, dla którego rejestr nie zawiera wpisu, a build go odrzuca z powodu braku zapisanego podpisu — jak opisuje Porównuje zapisane podpisy w obu plikach.

Aby przyjąć nową tożsamość, należy poprosić o nią z nazwy: aggrega pull --upgrade --release <release> <plugin>, podając plugin tak, jak nazywa go dołączenie w .aggrega-config.yaml, bez przyrostka wersji. Ponownie rozwiązuje to ten jeden plugin i przepisuje jego wpis, pozostawiając nietknięte każdą inną przypiętą zależność i każdą inną zapisaną tożsamość — i działa nawet wtedy, gdy plugin nie ma przypięcia w pliku blokady, ponieważ nazwany cel może też wskazywać jedno z tych dołączeń. Samo aggrega pull --upgrade, które ponownie rozwiązuje każdą zależność, ponownie rozwiązuje i przepisuje także każdą zapisaną tożsamość. Tak samo działa aggrega build --upgrade, które uruchamia pełne odświeżenie bez celu i nie pozwala wskazać pojedynczego celu.

Aby usunąć tożsamość, również należy poprosić o to z nazwy. Odłączenie pluginu od .aggrega-config.yaml nie usuwa jego wpisu, i jest to celowe: zwykłe aggrega pull nigdy wpisu nie usuwa. Należy uruchomić aggrega pull --upgrade --release <release> <plugin>, podając plugin tak, jak nazywa go rejestr — jego współrzędną tożsamości, czyli ciąg wypisywany przez opisane niżej zatrzymanie — a wpis zostanie usunięty, przy czym każda inna przypięta zależność i każda inna zapisana tożsamość pozostaną nietknięte. Samo aggrega pull --upgrade usuwa każdy wpis, którego nie wskazuje już żadne dołączenie werdyktu, w tym samym przebiegu, w którym ponownie rozwiązuje wszystko inne.

Usunięcie ostatniego wpisu pozostawia plik na miejscu, pusty, zamiast go usuwać. Pusty rejestr nic nie zawiera, więc niczego nie przypina i niczego nie zatrzymuje — tak samo jak brak rejestru — a zachowanie pliku sprawia, że usunięcie widać w jego diffie jako usunięcie.

Rejestr, który nie spełnia swojego schematu, zatrzymuje każde polecenie, które go odczytuje — budowanie, lint ograniczony do wydania oraz pull, także pull, który sam nie ma nic do zarejestrowania. Opróżniony rejestr i uszkodzony rejestr celowo traktowane są inaczej: opróżnienie to sposób usunięcia ostatniego wpisu, a opróżniony rejestr pozostaje cichy, natomiast plik, którego zawartości nie da się już sparsować, jest błędem, a nie pustym rejestrem — odczytanie go jako pustego sprawiłoby, że obcięcie pliku byłoby sposobem na wyłączenie porównania. Aby odzyskać sprawdzone tożsamości, należy przywrócić plik z systemu kontroli wersji.

Plugin serwowany z kopii wbudowanej w plik binarny kompilatora nie jest rejestrowany. Pull rejestruje to, co pozyskał — pobrał z rejestru albo odczytał z pamięci podręcznej — a z pliku binarnego nic nie jest pozyskiwane: te bajty są identyfikowane przez wersję kompilatora, która je zawiera, więc nie ma własnego rozwiązania do zarejestrowania. Dołączenie pluginu, który plik binarny już zawiera, nie tworzy więc dla niego wpisu. To rejestr ograniczający się do pozyskanych artefaktów, a nie rozwiązanie, które się nie powiodło.

Budowanie, lint ograniczony do wydania i walidacja ograniczona do wydania sprawdzają konfigurację obszaru roboczego względem rejestru. Zanim uruchomi się którekolwiek z tych dołączeń, aggrega build, aggrega lint --release i aggrega validate --release — a także te same operacje wywoływane przez aggrega serve i aggrega mcp — porównują dołączenia werdyktowe wskazane w konfiguracji z wpisami zawartymi w rejestrze. Plugin, którego skrót rozwiązanego artefaktu nie jest skrótem zarejestrowanym, zostaje odrzucony zamiast uruchomiony. Wpis rejestru, któremu nie odpowiada żadne skonfigurowane dołączenie werdyktowe, zatrzymuje przebieg: bramka, która została sprawdzona, a teraz jej brak, pozostawia wynik nieodróżnialny od wyniku zatwierdzonego przez tę bramkę, czego właśnie nie widzi osoba czytająca wynik. Komunikat zatrzymania wskazuje plugin i proponuje dwa rozwiązania zależne od intencji — ponowne dołączenie pluginu, jeśli usunięcie było pomyłką, albo uruchomienie opisanej wyżej jawnej aktualizacji, jeśli było zamierzone — i wypisuje tę aktualizację gotową do uruchomienia. Kierunek odwrotny — dołączenie, którego rejestr jeszcze nie zawiera — to opisane wyżej pierwsze wystąpienie i żadne z porównań na nim się nie zatrzymuje; wymóg podpisu to jedyne ograniczenie, którego dołączenie bez wpisu nie omija. Te same trzy interfejsy przy ładowaniu sprawdzają każdy plugin odczytany z pamięci podręcznej względem podpisu zapisanego w jego wpisie, jak strona budowania opisuje to dla budowania. Zakresy lintu obejmujące cały katalog i pojedynczą encję nie korzystają z rejestru.

Walidacja jest sprawdzana względem rejestru, ponieważ uruchamia te same kontrole co budowanie. aggrega validate --release dociera do każdej kontroli, do której dociera aggrega build, z wyjątkiem zapisu artefaktów, łącznie z pluginami bramkującymi — dzięki temu „to się waliduje” znaczy to samo co „to się buduje” — więc tożsamość uruchamianego pluginu jest porównywana z rejestrem dokładnie tak jak przy budowaniu. Pozostałe zakresy aggrega validate nie są względem niego sprawdzane: walidacja całego katalogu, pojedynczej encji lub pliku binarnego pluginu w ogóle nie odczytuje dołączeń pluginów obszaru roboczego, więc nie uruchamia się w nich żaden plugin werdyktowy i rejestr nie ma czego sprawdzać.

Sprawdzenie konfiguracji względem rejestru ustala obecność i tożsamość, i nic poza nimi. Ustala, że każda bramka wskazana w rejestrze jest nadal dołączona i że każda uruchamia się z artefaktu dla niej zarejestrowanego. Nie ustala, że bramka, która się uruchomiła, w ogóle zwróciła werdykt, a jeden taki przypadek nie jest nigdzie wychwytywany: dołączenie, którego function wskazuje eksport, który plugin rzeczywiście deklaruje, ale który nie jest eksportem werdyktu odczytywanym przez jego gniazdo, i którego wynik nie zawiera żadnego pola najwyższego poziomu spoza kształtu oczekiwanego przez to gniazdo — najprostszym przykładem jest pusty obiekt — uruchamia się, nie zwraca niczego, co mogłoby spowodować odrzucenie, i przepuszcza budowanie. Jego wynik jest nieodróżnialny od wyniku zatwierdzającej bramki i żadne porównanie z rejestrem nie może tego zauważyć, ponieważ z rejestrem wszystko jest w porządku: uruchomiony plugin jest dokładnie tym zarejestrowanym, po prostu niczego nie wykonał. Dwa sąsiednie przypadki powodują zatrzymanie, więc granica nie jest szersza, niż wynika z opisu — function wskazujące eksport, którego plugin nie deklaruje, jest odrzucane przy ładowaniu pluginu, a wynik zawierający pole najwyższego poziomu niezadeklarowane w kształcie gniazda jest odrzucany, zamiast zostać odczytany jako lista werdyktów, która akurat jest pusta. Zarejestrowana tożsamość sama w sobie nie wystarcza więc, by bramka cokolwiek oceniła.

Zarejestrowany skrót obejmuje pluginy, które obszar roboczy rozwiązuje z pamięci podręcznej wypełnianej przez aggrega pull, i nic, co rozwiązuje w inny sposób. To rozwiązanie, którym zwykle przechodzi dołączenie werdyktowe — nic nie przypina go w pliku blokady, więc jego bajty pochodzą z pamięci podręcznej, i właśnie przy tym odczycie rozwiązany skrót jest porównywany z zarejestrowanym. Plugin werdyktowy rozwiązywany przez obszar roboczy w inny sposób nigdy nie dociera do tego odczytu i podlega temu, co obejmuje sposób, w jaki został rozwiązany, a nie rejestrowi: bajty serwowane z kopii wbudowanej w plik binarny kompilatora są identyfikowane przez wersję kompilatora, która je zawiera, plik .wasm leżący obok swojej encji katalogu jest plikiem we własnym katalogu katalogu, jawna ścieżka w systemie plików jest wskazaną ścieżką, a plugin z przypięciem w pliku blokady podlega temu przypięciu. Druga połowa sprawdzania konfiguracji względem rejestru nie jest w ten sposób ograniczona: każdemu wpisowi w rejestrze nadal musi odpowiadać skonfigurowane dołączenie, niezależnie od tego, jak ten plugin jest rozwiązywany. Rejestr ustala więc, że wskazane w nim bramki są nadal dołączone, bez względu na to, co je serwuje, i ustala tożsamość artefaktów tych, które są serwowane z pamięci podręcznej.

Respektowanie a aktualizowanie

Domyślnie aggrega pull respektuje istniejący plik blokady: zależność już przypięta jest rozwiązywana do dokładnie przypiętej wersji (weryfikowanej względem przypiętego skrótu), rozwiązywane i dodawane są tylko odwołania, które nie są jeszcze przypięte, a przypięcia odwołań, do których encja Release już nie sięga, są usuwane. Ponowne pobranie niezmienionej encji Release niczego więc nie zmienia — odtwarza ten sam plik blokady bajt w bajt (łącznie z generated_at). Dodanie nowej zależności lub pobranie po ręcznej edycji, która usunęła przypięcie, rozwiązuje tylko tę lukę i pozostawia każde inne przypięcie nietknięte.

Zależność, którą ponowne pobranie odczytuje z pamięci podręcznej, jest zapisywana dokładnie tak, jak zapisało ją pobranie, które ją ściągnęło. Jej wiersz zachowuje wersję, skrót treści digest i manifest_digest — ten ostatni wzięty z manifestu przechowywanego obok treści w pamięci podręcznej — wraz z wartościami signature i deprecation, które tamto pobranie zweryfikowało w rejestrze. Żadna z tych wartości nie jest ponownie sprawdzana, dopóki kompilacja zaakceptowałaby wiersz, a --detail zgłasza taką zależność jako cache-reuse, więc ponowne pobranie, którego wszystkie zależności są w pamięci podręcznej, przy pliku blokady zapisującym każdy podpis wymagany przez konfigurację zaufania i wyłącznie podpisy akceptowane przez kompilację, zapisuje ten sam plik blokady niezależnie od tego, czy rejestr jest osiągalny.

Ponowne pobranie sprawdza podpis ponownie dokładnie tam, gdzie kompilacja odrzuciłaby wiersz, a takie wiersze są dwa.

  • Wymagany podpis, którego plik blokady nie zapisuje. Gdy konfiguracja zaufania wymaga podpisu dla zależności serwowanej z pamięci podręcznej, a wiersz pliku blokady nie zapisuje żadnego — wiersz został zmieniony, plik blokady zapisano od nowa na pamięci podręcznej wypełnionej przez wcześniejsze pobranie albo wymaganie dodano po pobraniu, które zapisało wiersz — ponowne pobranie prosi rejestr tej zależności o jej podpis, według skrótu manifestu przechowywanego obok niej w pamięci podręcznej, dokładnie tak jak dla zależności, którą ściąga, i zapisuje zweryfikowany podpis w wierszu. Taki wiersz kompilacja odrzuca (No verified signature is recorded for an artifact that requires one (Dla artefaktu, który go wymaga, nie zapisano zweryfikowanego podpisu)), więc to ponowne pobranie usuwa przyczynę tego odrzucenia. Rejestr, który nie dołącza podpisu, lub podpis nieakceptowany przez konfigurację zaufania zatrzymują ponowne pobranie tak samo, jak zatrzymują pobranie, które ściągnęło zależność. Ustawienia pozwalające pobraniu przyjąć zależność bez podpisu pozostawiają taki wiersz bez zmian i o nic nie pytają: skip_signature_verification na najwyższym poziomie, ten sam przełącznik we własnym wpisie rejestru z wyjątkiem rodzaju, którego wymaga obowiązująca w całym obszarze roboczym polityka podpisywania, oraz rejestr oznaczony jako advisory.
  • Zapisany podpis, którego kompilacja nie akceptuje. Gdy wiersz zapisuje podpis, którego zbuforowany pakiet podpisu usunięto lub zmieniono po pobraniu, które go zbuforowało — albo signature skopiowany z innego wiersza, którego pakiet jest nienaruszony, ale został utworzony dla innego artefaktu — kompilacja odrzuca wiersz niezależnie od wymagania podpisywania (A cached signature bundle does not match the digest recorded for it (Zbuforowany pakiet podpisu nie odpowiada zapisanemu dla niego skrótowi), A recorded signature was made for a different artifact (Zapisany podpis utworzono dla innego artefaktu)). Dlatego ponowne pobranie ponownie pyta rejestr tej zależności o jej podpis, niezależnie od wymagania, przez tę samą weryfikację, jaką przechodzi ściągana zależność: to, co ona zweryfikuje, zastępuje podpis wiersza, a wskazany przez nią pakiet jest ponownie buforowany, przy czym zbuforowana kopia, która nie odpowiada już swojemu skrótowi, zostaje nadpisana — tak że wiersz i pamięć podręczna zawierają to, co pozostawiło pobranie, które ściągnęło zależność. Podpis nieakceptowany przez konfigurację zaufania zatrzymuje ponowne pobranie tak, jak zatrzymuje pobranie, które ściągnęło zależność, i tak samo działa rejestr niedołączający podpisu tam, gdzie podpis jest wymagany. Gdy weryfikacja niczego nie zapisuje — skip_signature_verification tam, gdzie ma zastosowanie, co o nic nie pyta, rejestr niedołączający podpisu tam, gdzie nie jest on wymagany, lub rejestr advisory, w którym nic się nie weryfikuje — podpis wiersza zostaje wyczyszczony, co kompilacja przyjmuje przy tych samych ustawieniach.

O wiersz, którego zapisany podpis kompilacja akceptuje, nie pyta się ponownie, podobnie jak o wiersz bez podpisu, dla którego nic podpisu nie wymaga.

O zależność nazwaną bez rejestru, w obszarze roboczym, który nie wskazuje już default_registry, nie można zapytać. Jej wiersz został powiązany z rejestrem przez pobranie, które zapisało jej podpis, a bez rejestru domyślnego nie ma kogo zapytać. Gdy taki wiersz zapisuje podpis, którego kompilacja nie akceptuje, ponowne pobranie zatrzymuje się z tym samym odrzuceniem co kompilacja, informując, że nie skonfigurowano rejestru, by ponownie zapytać o wiersz, i pozostawia plik blokady bez zmian. Naprawia to skonfigurowanie rejestru, z którego pochodzi zależność, jako default_registry i ponowne pobranie.

To respektowanie dotyczy tego, co serwuje rejestr lub pamięć podręczna. Encja dostarczana przez lokalny katalog jest rozwiązywana z tego katalogu, w wersji deklarowanej przez jej plik, a wpis, który plik blokady dla niej zapisuje, nie jest przy tym uwzględniany. Plik blokady nadal zapisuje taką encję, więc będzie ona tam widoczna — ale ręczna edycja tego wpisu nie utrzyma encji w wpisanej wersji, a następne uzgodnienie nadpisze wpis zgodnie z plikiem. Aby zmienić wersję lokalnie dostarczanej encji, którą rozwiązuje encja Release, należy edytować plik katalogu, a nie plik blokady.

Przypięcie wskazuje bajty, a nie miejsce, więc wpis pamięci podręcznej, który nie zawiera już swojego przypięcia, jest pomijany, a nie uznawany za zaufany. Encja edytowana w miejscu — nowa treść pod tą samą version — pozostawia w pamięci podręcznej treści wcześniejszą treść pod tą nazwą i wersją. Katalog jest odczytywany jako pierwszy, więc encja, którą nadal dostarcza, jest przypinana z jego pliku, a nieaktualny wpis nigdy nie jest odczytywany. Renderowanie, które pobranie wykonuje, aby wykryć zewnętrzne dane wejściowe encji Release, odczytuje każde przypięcie tak jak kompilacja, z katalogu zawierającego przypięte bajty, i zgłasza pominięty wpis komunikatem, który wypisuje aggrega build. Gdy żaden katalog nie dostarcza encji, a rejestr jest osiągalny, pobranie ponownie ściąga przypiętą wersję, nadpisuje wpis i informuje o tym na standardowym wyjściu błędów, podając wpis i oba skróty:

reuse: cache entry for <name>:<version> held <digest the entry held>, not the pinned <pinned digest>; refreshed from the registry (pin unchanged)

Ściągnięte bajty są sprawdzane względem przypięcia jak każde ściągnięcie z przypięciem, więc rejestr serwujący inne bajty pod tą wersją zatrzymuje pobranie, jak opisano poniżej. Gdy żadne źródło nie zawiera przypiętych bajtów — żaden katalog nie dostarcza encji, wpis pamięci podręcznej zawiera inne bajty, a żaden rejestr nie serwuje przypiętej wersji lub uruchomienie nie dociera do żadnego — pobranie i aggrega pull --verify zatrzymują się z E0135 — lub E0133, gdy manifest wpisu pamięci podręcznej nie jest tym, który przypina plik blokady — podając każde odczytane źródło i to, co zawierało; gdy uruchomienie nie dotarło do żadnego rejestru, komunikat wskazuje też krok, który ponownie ściąga przypiętą wersję.

Aby zaktualizować przypięte wersje, należy uruchomić aggrega pull --upgrade --release <release> — polecenie odrzuca istniejące przypięcia i ponownie rozwiązuje wszystkie zależności do najnowszych spełniających wymagania wersji. Aktualizacja jest jawnym działaniem; domyślne zachowanie nigdy nie przesuwa przypiętej zależności. Odzwierciedla to konwencję npm ci / cargo / go build (domyślnie realizowana jest blokada; aktualizacja wymaga jawnego włączenia) i to właśnie czyni automatyczne pobieranie w aggrega build bezpiecznym — kompilacja rozwiązuje dokładnie to, co przypina plik blokady, nigdy po cichu nie zmieniając wersji.

Ta forma bez argumentów usuwa każde zapisane przypięcie, więc przed jakimkolwiek działaniem prosi o potwierdzenie. Do użytku nieinteraktywnego można odpowiedzieć z góry za pomocą --yes; gdy standardowe wejście nie jest terminalem i brak --yes, polecenie odmawia, zamiast czekać na odpowiedź, której nikt nie może udzielić. Wskazanie celów (aggrega pull --upgrade --release <release> <uri>) zachowuje każde przypięcie, którego nie wskazano, więc ta forma o nic nie pyta. aggrega build --upgrade uruchamia formę bez argumentów i podlega tym samym warunkom.

Jeśli bajty przypiętej wersji w rejestrze nie odpowiadają już skrótowi zapisanemu w pliku blokady (naruszenie niezmienności po stronie źródła), pull zatrzymuje się z błędem integralności, zamiast po cichu przyjąć zmienione bajty — aby świadomie przypiąć wersję ponownie, należy uruchomić --upgrade.

Sprawdzanie pliku blokady bez jego zapisywania

aggrega pull --verify --release <release> odpowiada na jedno pytanie: czy uruchomienie aggrega pull teraz zmieniłoby plik blokady albo rejestr zaufania wtyczek obok niego? Wykonuje rozwiązywanie, które wykonałby pull, porównuje z nim plik blokady i rejestr, po czym zatrzymuje się, zanim zostanie zapisane cokolwiek, co pull zatwierdza — plik blokady, rejestr zaufania wtyczek i każdy entity.lock pozostają bez zmian. Kończy się kodem niezerowym, gdy brakuje pliku blokady, oraz przy każdej różnicy, wymieniając każdą z nich. Znaczniki wycofania nie są porównywane, jak opisano poniżej. Jest odrzucane w połączeniu z --upgrade, z --dry-run oraz z --pin-sources niezależnie od wartości tej flagi: weryfikacja ani nie zapisuje przypięcia, którego brakuje w entity.lock, ani nie zatrzymuje się z jego powodu, więc flaga niczego by nie zmieniła.

Respektuje zapisane przypięcia dokładnie tak jak pull. Zależność przypięta w pliku blokady jest rozwiązywana w przypiętej wersji i sprawdzana względem przypiętego skrótu, a encja dostarczana przez lokalny katalog jest rozwiązywana z tego katalogu, jak opisuje Respektowanie a aktualizowanie. Zatem:

  • Odwołanie, którego rejestr opublikował nowszą wersję od czasu pull, nie jest dryfem. Pull utrzymałby jego przypięcie, więc plik blokady nadal jest tym, który zapisałby pull; nowszą wersję przyjmuje się za pomocą aggrega pull --upgrade.
  • Rejestr, który pod przypiętą wersją serwuje teraz inne bajty, zatrzymuje weryfikację tym samym błędem integralności, który zatrzymuje pull, zamiast zgłaszać zmianę jako dryf.
  • Ręcznie edytowany wiersz pliku blokady, edytowana encja Release oraz encja edytowana w lokalnym katalogu są zgłaszane, ponieważ każda z nich stanowi różnicę między plikiem blokady a tym, co pull rozwiązuje teraz.

Odczytuje i wypełnia pamięć podręczną tak jak pull. Wpis przechowywany w pamięci podręcznej pod swoim przypięciem — encja katalogu lub plik .wasm wtyczki — jest odczytywany stamtąd bez odpytywania rejestru, co pozwala uruchomić weryfikację w trybie offline na obszarze roboczym wypełnionym wcześniej przez pull z dostępem do sieci. Wpis, którego pamięć podręczna nie zawiera, jest pobierany tak, jak pobiera go pull, a wpis, który nie odpowiada już swojemu przypięciu, jest traktowany dokładnie tak, jak traktuje go pull. Weryfikacja może więc dodawać do pamięci podręcznej, ale nigdy nie przesuwa przypięcia.

Porównuje zapisane podpisy w obu plikach

Podpis, który pull zweryfikował dla artefaktu, jest częścią tego, co zapisuje: signature we wpisie pliku blokady oraz we wpisie plugins-trust.yaml dla wtyczki podłączonej w roli werdyktu. Gdy przypięcia się zgadzają, weryfikacja porównuje każdy zapisany podpis z tym, który pull zapisałby teraz, i zgłasza każdy, który pull zapisałby tam, gdzie żaden nie jest zapisany, zastąpiłby lub usunąłby, pod błędem A recorded signature is not the one a pull would record (Zapisany podpis nie jest tym, który zapisałby pull). Każdy taki wpis, w którymkolwiek pliku, jest wymieniany w tym samym uruchomieniu.

To, które wpisy pliku blokady są sprawdzane, wynika z wyboru samego pull. Ponowny pull pyta rejestr o podpis wpisu dokładnie tam, gdzie opisuje to Respektowanie a aktualizowanie, a weryfikacja odczytuje ten sam wybór:

  • Dwa rodzaje wpisów są zgłaszane bez odpytywania rejestru, ponieważ pull przepisuje je niezależnie od odpowiedzi rejestru: wpis serwowany z pamięci podręcznej, który nie zapisuje podpisu, choć konfiguracja zaufania go wymaga — pull zapisuje podpis artefaktu lub zatrzymuje się, gdy nie da się go ustalić — oraz wpis, którego zapisany podpis został złożony dla innego artefaktu, a który pull zastępuje własnym podpisem artefaktu.
  • O każdy inny wpis, który pull sprawdziłby ponownie, odpytywany jest rejestr, ponieważ tylko odpowiedź rejestru mówi, czy pull by go zmienił: wpis, którego bajty ta weryfikacja pobrała, oraz wpis, którego zbuforowany pakiet podpisu został usunięty, jest nieczytelny lub został zmieniony. Weryfikacja pyta rejestr, tak jak zrobiłby to pull, i zgłasza wpis, gdy odpowiedź zapisuje, zastępuje lub usuwa jego podpis. Zweryfikowany pakiet podpisu jest buforowany tak, jak buforuje go pull, więc wpis, którego zbuforowany pakiet usunięto, a którego rejestr nadal serwuje zapisany podpis, przechodzi weryfikację i pozostawia naprawioną pamięć podręczną.

Wpis, którego zapisany podpis build akceptuje, oraz wpis bez podpisu, dla którego nic podpisu nie wymaga, nie są przedmiotem zapytań ani przy pull, ani przy weryfikacji.

Rejestr zaufania wtyczek jest porównywany z tym samym pull. Każdy pull weryfikuje w rejestrze podpis każdej wtyczki podłączonej w roli werdyktu i tak samo robi weryfikacja, która zgłasza wpis, którego podpis ta weryfikacja by zapisała, zastąpiła lub usunęła. Wtyczka, dla której rejestr zaufania nie ma wpisu, jest zgłaszana tam, gdzie build odrzuca ją z powodu braku zapisanego podpisu, ponieważ pull zapisuje wpis z jej podpisem, a build odrzuca wtyczkę do tego czasu. Każda inna to pierwsze wystąpienie, którego weryfikacja nie zgłasza, tak jak nie zgłasza żadnej tożsamości, której rejestr zaufania jeszcze nie zawiera. W trybie offline weryfikacja nie pyta żadnego rejestru o te wtyczki, a sekcja Offline opisuje, co zgłasza w zamian.

Znaczniki wycofania nie są porównywane. Znacznik dołączony do artefaktu po pull jest stanem rejestru i zmienia się bez żadnej zmiany w obszarze roboczym; weryfikacja kończąca się błędem z jego powodu oznaczałaby niepowodzenie sprawdzenia plików, których nikt nie modyfikował. Z tego samego powodu zapisany znacznik jest dla buildu jedynie ostrzeżeniem, a nie powodem zatrzymania. Pull może więc zapisać znacznik we wpisie, który przeszedł weryfikację.

Podgląd tego, co zapisałoby pobranie

aggrega pull --dry-run --release <release> rozwiązuje zależności dokładnie tak jak zwykłe pobranie, a następnie zamiast zapisywać wypisuje to, co zostałoby zapisane: jeden nagłówek z nazwą ścieżki każdego pliku, a po nim treść, jaką ten plik by zawierał.

aggrega pull --dry-run --release release.yaml

Wymienia każdy plik, nie tylko plik blokady. Plik blokady, plik entity.lock obok każdej encji Recipe i FeatureRecipe, której zapisane przypięcia zmieniłyby się przy --pin-sources, oraz rejestr zaufania wtyczek pojawiają się w tym samym raporcie, ponieważ podgląd pokazujący tylko plik blokady sugerowałby, że zmienia się wyłącznie on. Pobranie, które zatrzymałoby się na nieprzypiętej encji, zatrzymuje się również przy --dry-run z tego samego powodu: podgląd pokazuje to, co zrobiłoby pobranie. Pliki, które pobranie pozostawiłoby bajt w bajt bez zmian, w ogóle się nie pojawiają — nazwa w raporcie oznacza, że dany plik zaraz się zmieni. Ostatni wiersz podaje ich liczbę, a dla obszaru roboczego, którego pobranie by nie zmieniło, raportowana liczba wynosi zero.

Nic na dysku się nie zmienia. Żaden plik blokady nie jest zapisywany ani tworzony, żadna blokada encji nie jest zapisywana ani usuwana, a żaden rejestr zaufania nie jest tworzony ani modyfikowany. Jeśli daną funkcjonalność udostępnia więcej niż jedna wtyczka dostawcy i nic nie rozstrzygnęło między nimi, uruchomienie zatrzymuje się, wskazując, co należy podać, zamiast proponować zapisanie wyboru w konfiguracji — podgląd nie edytuje przy okazji pliku konfiguracyjnego.

Samo rozwiązywanie nadal się odbywa, więc pamięć podręczna nadal się zapełnia. To, jakie dane zewnętrzne konsumuje encja Release, wynika z jej renderowania, a uruchomienie, które odmówiłoby rozwiązywania, nie miałoby czego raportować, dlatego --dry-run pobiera i zapisuje dane dokładnie tak jak pobranie. Zawartość .aggrega/cache jest odczytywana wyłącznie poprzez przypięcia zapisane w pliku blokady, więc jej zapełnienie nie zmienia niczego, co rozwiązuje kompilacja; przebieg próbny pokazuje to, co zapisałoby pobranie.

Samo --upgrade nie wymaga przy tej fladze żadnego potwierdzenia. Potwierdzenie istnieje, ponieważ pełne odświeżenie usuwa każde zapisane przypięcie, a podgląd nie usuwa żadnego — dlatego aggrega pull --dry-run --upgrade --release <release> to forma, po którą należy sięgnąć, gdy chce się wiedzieć, ile kosztowałoby odświeżenie; działa ona bez odpowiedzi.

Nie jest akceptowana razem z --verify, które i tak nie zapisuje żadnego z tych plików. Takie połączenie sprawiałoby, że flaga nic by nie robiła, a wyglądałoby, jakby coś zrobiła, dlatego jest odrzucane, a nie ignorowane.

Jednej rzeczy podgląd z przypinaniem nie zawsze może pokazać w całości i informuje o tym, gdy do tego dochodzi. Pobranie z przypinaniem przepisuje plik entity.lock obok każdej encji Recipe i FeatureRecipe, a następnie renderuje encję Release, aby wykryć jej dane zewnętrzne; podgląd pozostawia te blokady bez zmian, więc jeśli zapisane w nich przypięcie stało się nieaktualne — na przykład zaimportowany plik został zmieniony po przypięciu — renderowanie jest weryfikowane względem nieaktualnego skrótu, który wciąż zapisuje niezapisana blokada, i zatrzymuje się. Wszystko inne w raporcie jest dokładnie tym, co zapisałoby pobranie; niekompletne są tylko przypięcia danych zewnętrznych w raportowanym pliku blokady. Uruchomienie informuje o tym zarówno w wyjściu, jak i w diagnostyce, zamiast przekazywać plik blokady, który wygląda na kompletny. Pierwsze rozwiązywanie obszaru roboczego nie jest tym dotknięte, ponieważ nie ma jeszcze zapisanego skrótu, względem którego cokolwiek mogłoby być nieaktualne.

Kompozycja opisywana przez te przypięcia

Plik blokady przypina to, co zużyje kompilacja tej encji Release, dlatego rozwiązywanie odtwarza tę samą kompozycję co ta kompilacja: rozwiązuje dokumenty, stosuje transformacje deklarowane przez załączniki obszaru roboczego i poddaje wynik kontrolom, które kompilacja wykonuje na gotowym grafie. Wynikają z tego dwie rzeczy i obie ujawniają się w przebiegu zapisującym plik blokady, a nie przy pierwszej kompilacji, która go odczytuje.

Kompozycja odrzucona przez te kontrole zatrzymuje pobieranie. Krawędź uses:, której cel nie spełnia selector: jej gniazda, encja Feature dołączona do komponentu, którego jej appliesTo: nie dopuszcza, oraz każde inne naruszenie zgłaszane przez te kontrole zatrzymują to polecenie z tą samą diagnostyką, którą wypisuje kompilacja tych samych dokumentów — a zatrzymanie wymienia wszystkie znalezione problemy w jednym uruchomieniu, a nie tylko pierwszy, więc jeden przebieg daje całą listę do poprawienia. Dzieje się to przed zapisem, więc <release-stem>.lock i plugins-trust.yaml pozostają dokładnie takie, jakie były, a encja Release, której nie da się skompilować, nigdy nie zostaje zapisana jako rozwiązana poprawnie. Nie obejmuje to załączników zwracających werdykt: żaden załącznik ir-verdict ani render-verdict nie jest tu uruchamiany, więc odrzucający werdykt zatrzymuje kompilację, lint w zakresie wydania lub walidację w zakresie wydania, które go wywołują, a nie to polecenie.

Załącznik w roli kształtującej graf jest uruchamiany podczas tego przebiegu, więc wtyczka, której nie da się rozwiązać, zatrzymuje pobieranie. Załącznik label-transform ustala etykiety węzłów, zanim cokolwiek zostanie do nich dopasowane, a załącznik annotation-transform wstrzykuje adnotacje, które rozwijają się w załączniki encji Feature — oba zmieniają zawartość grafu, więc odtworzenie grafu oznacza ich wywołanie, a wywołanie oznacza posiadanie bajtów każdej wtyczki. Wtyczka, której bajtów ten przebieg nie może uzyskać, zatrzymuje uruchomienie z podaniem wtyczki i tego, czego nie udało się dla niej znaleźć — to samo odrzucenie, które wykonuje kompilacja tego samego obszaru roboczego, gdy nie może ich uzyskać. Wywoływana jest lista załączników właśnie rozwiązana przez ten przebieg, wraz z ustawieniami i plikami definicji, które plik blokady zapisuje, aby późniejsza kompilacja mogła je odtworzyć, więc oba przebiegi uruchamiają ten sam załącznik na tych samych danych wejściowych.

Encja Plugin wskazana przez krok potoku, której nic nie przechowuje, również zatrzymuje pobieranie. Każda encja Plugin wskazana w pipeline encji Recipe lub FeatureRecipe jest rozwiązywana razem z pozostałymi zależnościami encji Release — z katalogu katalogowego, z kopii wbudowanej w plik binarny kompilatora, z pamięci podręcznej treści lub z rejestru — a taka, której żadne z nich nie przechowuje, nie mogłaby zostać załadowana także przez kompilację. Dlatego pobieranie zatrzymuje się, zanim cokolwiek zapisze, podając encję Plugin oraz encję Recipe lub FeatureRecipe, której potok ją wskazuje, z tym samym warunkiem, który zgłasza kompilacja po dotarciu do tego kroku (A plugin reference is not a Plugin entity (Odwołanie do wtyczki nie jest encją Plugin)). Dotyczy to każdej encji Recipe i FeatureRecipe powiązanej przez Manifest, również takiej, której nic w tej encji Release nie dołącza, ponieważ każda jest rozwiązywana i przypinana niezależnie od tego, czy jest renderowana. Należy opublikować encję Plugin albo umieścić ją w katalogu katalogowym wraz ze zbudowanym plikiem .wasm obok, a następnie ponownie wykonać pobieranie.

To zatrzymanie i uruchomienie z ograniczeniami to celowo różne wyniki. Renderowanie, którego nie da się dokończyć — opisane zarówno w sekcji Jak rozwiązywanie znajduje zewnętrzne dane wejściowe, jak i Tryb offline — pozostawia wszystkie przypięcia zależności poprawne, więc przypięcia są zapisywane, a brak jest zgłaszany. Kompozycja odrzucona przez kontrole nie jest brakiem w tym, co rozwiązano: to encja Release, której nie da się skompilować, więc nic nie zostaje dla niej przypięte, a uruchomienie się zatrzymuje.

Pamięć podręczna

Pobrana zawartość jest przechowywana w .aggrega/cache, podzielona na poddrzewo entities/ dla encji katalogowych, poddrzewo source-artifacts/ dla artefaktów źródłowych oraz poddrzewo inputs/ dla wejść zewnętrznych, które konsumuje renderowanie. Slot encji katalogowej jest nazywany jej rodzajem, współrzędną i wersją (więc encja Component i encja Recipe o wspólnej współrzędnej i wersji zachowują dwa sloty), slot artefaktu źródłowego — miejscem, z którego go pobrano, jego wersją i prefiksem skrótu jego zawartości, a slot wejścia zewnętrznego — skrótem jego zawartości; to, co kompilacja odczytuje z któregokolwiek z nich, jest sprawdzane względem zapisu w pliku blokady. Identyczne przypięcia wersji współdzielą zatem jeden slot między encjami Releases. Każdy slot artefaktu źródłowego zawiera autorytatywne archiwum, regenerowaną wypakowaną kopię i mały plik metadanych; wypakowana kopia jest regenerowana przy każdym odczycie, więc wynik kompilacji zależy od archiwum i pliku blokady, a nie od stanu wypakowanych plików.

Każda nazwa, którą pamięć podręczna wyprowadza z wartości, jest akceptowana przez Windows, Linux i macOS. Współrzędna, wersja, host rejestru lub skrót zawierają znaki niedozwolone w nazwie pliku: / między częściami współrzędnej, : przed wersją, wewnątrz sha256: i przed portem rejestru. Dlatego każda wartość — rodzaj, współrzędna, wersja, host rejestru lub skrót — jest zapisywana w odpowiedniej postaci, zanim stanie się nazwą katalogu lub pliku — mała litera, cyfra, ., _ i - są zapisywane bez zmian, a każdy inny znak jest zapisywany jako sekwencja ucieczki zaczynająca się od +. Encja Component core/devtool/adminer:1.0.0 w wersji 1.0.0 to slot entities/+zx000043omponent/core+zsdevtool+zsadminer+zx00003a1.0.0/1.0.0/, a slot nazwany skrótem zawartości to sha256+zx00003a<hex>. Wielka litera również jest zastępowana sekwencją ucieczki, więc dwie współrzędne różniące się tylko wielkością liter zachowują dwa sloty w systemie plików ignorującym wielkość liter; nazwa zarezerwowana przez Windows dla urządzenia, taka jak con, ma pierwszą literę zastąpioną sekwencją ucieczki; żadna nazwa nie kończy się kropką. Dwie różne wartości nigdy nie mają wspólnej nazwy, a jedna wartość ma tę samą nazwę na każdej maszynie. aggrega cache status wymienia każdy wpis według wartości, z których zapisano jego nazwy — encję katalogową według jej współrzędnej, wersji i rodzaju — a nie według zapisanych nazw.

Wpis archiwum zachowuje nazwę nadaną mu przez wydawcę, więc w systemie Windows wpis, którego Windows nie może przechować, jest odrzucany. Pliki zawarte w archiwum artefaktu źródłowego lub encji katalogowej są rozmieszczane pod nazwami nadanymi im w archiwum, a nie przekształcanymi przez pamięć podręczną. Jeśli wypakowywanie odbywa się w systemie Windows, wpis zawierający część, której Windows nie może przechować w zapisanej postaci — nazwę zarezerwowaną dla urządzenia, taką jak NUL lub aux, w dowolnej wielkości liter i z rozszerzeniem lub bez, albo część kończącą się kropką lub spacją — jest odrzucany z błędem E0340, który podaje nazwę wpisu, i nic z tego archiwum nie jest rozmieszczane. W systemach Linux i macOS taki wpis jest rozmieszczany pod swoją nazwą. Wpis wychodzący poza katalog wypakowywania jest odrzucany na każdej maszynie.

Slot encji katalogowej jest wpisem tylko wraz ze swoim manifestem. Slot zawiera zawartość udostępnioną przez rejestr, a obok niej manifest opisujący tę zawartość. Slot zawierający samą zawartość — po pobieraniu przerwanym między dwoma zapisami lub z plikiem umieszczonym tam ręcznie — nie jest wpisem: pull, także weryfikujący, ponownie prosi o nią rejestr encji, jeśli jest osiągalny, natomiast kompilacja, która nigdy niczego nie pobiera, traktuje encję jako brakującą, tak jak pull, gdy żaden rejestr nie jest osiągalny.

To, co trafia do pamięci podręcznej, musi spełniać dwa warunki: mieć kształt opisany przez własny schemat encji i trafić w miejsce, które pamięć podręczna dla niego wyznacza. Treść pobrana z rejestru jest przed zapisaniem w pamięci podręcznej sprawdzana schematem swojego rodzaju — tym samym sprawdzeniem, które ją potem odczytuje — więc opublikowana encja lub biblioteka udostępniana przez rejestr, którą odrzuca jej własny schemat, zatrzymuje pull z podaniem tego, co pobrano, zamiast trafić do pamięci podręcznej i ujawnić się później jako błąd. Z kolei wartość, z której budowana jest lokalizacja w pamięci podręcznej, a która umieściłaby plik gdzie indziej niż w miejscu przez nią wskazanym — wersja będąca ścieżką zamiast wersji, ścieżka url źródła lub module_subdir wychodzące ponad swoje miejsce — jest odrzucana w chwili budowania lokalizacji z podaniem błędnej wartości. Wartość zapisana w tworzonej przez siebie encji Recipe lub FeatureRecipe podlega temu samemu w chwili budowania z niej lokalizacji w pamięci podręcznej — a module_subdir źródła git wcześniej, przed pobraniem repozytorium, jak opisano niżej.

Repozytorium git jest archiwizowane z własnej kopii roboczej. Dla źródła git-repository pull pobiera kopię roboczą repozytorium w przypiętym commicie i archiwizuje katalog wskazany przez module_subdir albo całe repozytorium. module_subdir, który w zapisanej postaci wychodzi ponad repozytorium — ../shared lub ..\shared — jest odrzucany przed pobraniem repozytorium z błędem E0307 przytaczającym tę wartość, więc nic poza kopią roboczą nie jest odczytywane. Dowiązanie symboliczne zatwierdzone w repozytorium jest archiwizowane jako plik lub katalog, na który wskazuje, o ile leży on wewnątrz repozytorium — samo module_subdir może być takim dowiązaniem. Dowiązanie prowadzące poza repozytorium zatrzymuje pull z błędem E0321, podającym dowiązanie i miejsce, do którego prowadzi, i nic nie trafia do pamięci podręcznej, więc repozytorium, z którego wykonuje się pull, nie może sprawić, że pull skopiuje plik z lokalnej maszyny do artefaktu. Kopia robocza jest usuwana po zakończeniu pull, dlatego komunikat podaje dowiązanie według jego miejsca w repozytorium oraz repozytorium i rewizję wskazane przez źródło, a nie katalog, który już nie istnieje. Zmiana dowiązania należy do repozytorium. Granica obszaru roboczego opisuje regułę, którą to stosuje.

Pamięć podręczna jest zakotwiczona w obszarze roboczym, a nie w katalogu, z którego uruchomiono polecenie, więc jeden obszar roboczy ma jedną pamięć podręczną, a pull uruchomiony z podkatalogu wypełnia ten sam magazyn, który odczytuje kompilacja uruchomiona z katalogu głównego.

Pull, dla którego nie znaleziono ani nie wskazano obszaru roboczego, jest odrzucany, zanim cokolwiek zostanie pobrane. Gdy nic nie wskazuje katalogu głównego, a wykrywanie niczego nie zakotwicza — ani z folderu, w którym uruchomiono polecenie, ani, dla encji Release wskazanej ścieżką bezwzględną, z folderu tej encji Release — katalogiem głównym byłby ten folder, a zapisana pod nim pamięć podręczna uczyniłaby go obszarem roboczym. Dlatego pull się zatrzymuje, nie zapisuje pliku blokady ani pamięci podręcznej i podaje folder oraz dwa wyjścia: wskazać obszar roboczy za pomocą --workspace-root lub AGGREGA_WORKSPACE_ROOT albo umieścić w tym folderze plik .aggrega-config.yaml z blokiem workspace:. Narzędzie pull w aggrega mcp, wywołane bez workspace_root na serwerze uruchomionym bez katalogu głównego, jest odrzucane w ten sam sposób; Konfiguracja wymienia pozostałe polecenia, których to dotyczy.

Budowanie tam, gdzie sieć jest niedostępna

Ponieważ to polecenie jest jedynym krokiem, który sięga na zewnątrz, jedno uruchomienie z dostępem do sieci wystarcza, aby każda późniejsza kompilacja była lokalna. To uruchomienie zapisuje plik blokady i wypełnia pamięć podręczną obszaru roboczego bajtami wskazanymi przez te przypięcia, a kompilacja nie potrzebuje potem niczego poza nimi.

Na odłączoną maszynę trafiają trzy rzeczy:

  • Encja Release i jej plik blokady. Należy zatwierdzić <release-stem>.lock obok encji Release; to on wskazuje kompilacji, do jakiej wersji i skrótu rozwiązano każdą zależność.
  • plugins-trust.yaml, jeśli obszar roboczy dołącza wtyczkę zwracającą werdykt. Kompilacja porównuje dołączenia werdyktowe wskazane w jej konfiguracji z tym rejestrem, zanim którekolwiek z nich zostanie uruchomione, więc przeniesienie rejestru wiąże odłączoną kompilację z tożsamościami, które zostały przejrzane, i z podpisami, które pull dla nich zweryfikował. Należy go zatwierdzić obok pliku blokady, jak opisuje Rejestr zaufania wtyczek.
  • Katalog pamięci podręcznej. Znajdują się w nim encje, artefakty źródłowe i przypięte dane wejściowe, a wszystko, czego nie dostarcza lokalny katalog catalog_dirs, jest odczytywane stamtąd.

Na odłączonej maszynie kompilację uruchamia się jak zwykle. Warto tam ustawić tryb offline, mimo że kompilacja na wypełnionym pliku blokady odczytuje swoje domknięcie z pamięci podręcznej: zamienia on potencjalne sięgnięcie do sieci w natychmiastową odmowę wskazującą ten tryb, zamiast próby połączenia, która musi najpierw przekroczyć limit czasu. Wszystko, czego nie ma w pamięci podręcznej, i każde zewnętrzne dane wejściowe, których plik blokady nie przypina, zatrzymuje kompilację ze wskazaniem, czego brakuje i jakie rozwiązanie by to przypięło — nic nie jest pobierane po cichu, aby uzupełnić lukę.

Maszyna odizolowana od sieci (air gap) i obszar roboczy w trybie offline to różne twierdzenia i warto tę różnicę zachować. Maszyna za izolacją sieciową może mieć lokalną kopię rejestru lub katalog catalog_dirs zawierający wszystko, czego potrzebuje; wtedy zwykły pull na tej maszynie da się zrealizować bez sięgania na zewnątrz. Tryb offline opisuje, po co polecenie może sięgać, a nie to, co maszyna przechowuje; sekcja Offline przedstawia, czego odmawia, a czego nie dotyka.

Tryb offline

W trybie offline — ustawianym kluczem najwyższego poziomu offline w pliku konfiguracyjnym, zmienną AGGREGA_OFFLINE w środowisku lub flagą --offline w wierszu poleceń — aggrega pull odmawia dostępu do sieci. Odmowa następuje przed jakąkolwiek próbą połączenia, a nie jako przekroczenie limitu czasu w trakcie pobierania, więc pull w trybie offline nie łączy się z żadnym rejestrem ani żadnym zdalnym źródłem. Jeśli tryb ustawił zatwierdzony plik lub wyeksportowana zmienna, a trzeba go pominąć dla jednego polecenia, --offline=false zezwala na dostęp do sieci tylko dla tego uruchomienia.

--upgrade jest w tym trybie odrzucana bezwarunkowo i jest to jedyna taka opcja. Pełne odświeżenie podnosi każdą zależność do najwyższej wersji, jaką rejestr aktualnie oferuje, więc musi zapytać rejestr, co aktualnie udostępnia. Zwykły pull tego nie wymaga: respektuje już zapisane przypięcia, rozwiązuje tylko to, co ich nie ma, i dlatego może zostać zrealizowany z zasobów dostępnych na maszynie. Komunikat odmowy wskazuje, które z trzech miejsc ustawiło tryb i jak zezwolić na dostęp do sieci dla jednego uruchomienia.

Rozwiązywanie korzysta wtedy wyłącznie z tego, co maszyna już posiada: stosu wyszukiwania catalog_dirs i pamięci podręcznej w .aggrega/cache. Jeśli katalog i pamięć podręczna spełniają każde odwołanie, pull w trybie offline kończy się normalnie i zapisuje zwykły plik blokady. Plik blokady zapisuje URI, rozwiązaną wersję i skrót każdej zależności, ale nigdy to, które z tych miejsc dostarczyło bajty — dlatego pull offline i pull online, które rozwiązują te same wersje, zapisują ten sam plik blokady.

Zależność, której pull w trybie offline nie może spełnić lokalnie, zatrzymuje go. Wpis nigdy nie jest pomijany:

  • Encja katalogu, której nie da się nigdzie rozwiązać, zatrzymuje pull, wskazując odwołanie i miejsce, z którego się do niej odwołano, tak że wskazana jest zarówno brakująca zależność, jak i to, co jej zażądało.
  • Zdalne source: zatrzymuje pull, wskazując źródło i informując, że należy albo zezwolić na dostęp do sieci, albo wypełnić pamięć podręczną ze środowiska z połączeniem.
  • Zależność przechowywana w pamięci podręcznej, której wymaganego podpisu plik blokady nie zapisuje lub której zapisanego podpisu build nie akceptuje, zatrzymuje pull z odmową trybu offline, wskazując tę zależność: zapisanie podpisu oznacza zapytanie jej rejestru, jak opisano w sekcji Respektowanie a aktualizowanie. Zezwolenie na dostęp do sieci dla tego jednego uruchomienia zapisuje podpis. Zapisany podpis, który build akceptuje, nie jest ponownie sprawdzany, więc nie zatrzymuje pulla w trybie offline.

Zewnętrzne wejście jest jedynym przypadkiem, który nie zatrzymuje pulla — zamiast tego jest zgłaszane. Renderowanie, które je wykrywa, nie może pobrać tego, czego jeszcze nie przechowano, więc pull w trybie offline dla encji Release z nieprzypiętym zewnętrznym wejściem kończy się, zapisuje każde rozwiązane przypięcie zależności i zgłasza trzy rzeczy: że renderowanie nie zostało ukończone, co zostało przypięte oraz że build tej encji Release zatrzyma się, wskazując URL. Zapisane przypięcia zależności są poprawne — nic w nich nie zależało od renderowania — więc są zachowywane, a nie odrzucane, by czytelnik musiał je odtwarzać.

Jest to zamierzone, a nie przeoczenie, i nie ma dla tego przełącznika. Pull, który odrzuciłby poprawną pracę, kosztowałby utratę części zakończonej powodzeniem; pull, który milczałby, dałby plik blokady wyglądający na kompletny, choć taki nie jest. Zgłoszenie tego jest jedynym wynikiem, który pozwala działać: wystarczy ponownie uruchomić pull ze środowiska z połączeniem lub z takiego, którego pamięć podręczna już przechowuje tę treść, a to samo polecenie ją przypnie.

Pull w trybie offline jest więc odmową użycia sieci, a nie okrojonym wynikiem dla wszystkiego, co wskazuje dokument, a w przypadku zewnętrznych wejść — ukończonym rozwiązywaniem, które informuje, czego nie mogło osiągnąć. Istniejący plik blokady to taki, którego rozwiązywanie zależności zostało ukończone; to, czy jego zewnętrzne wejścia są kompletne, mówią komunikaty samego pulla i to właśnie egzekwuje potem build.

--verify w trybie offline obejmuje mniej i to zgłasza. Sprawdzenie, na co dziś wskazuje zapisana referencja źródła, wymaga połączenia z jej zdalnym repozytorium, czego tryb offline odmawia. Dlatego --verify w trybie offline sprawdza przypięte zależności i pomija ten aspekt, wypisując wiersz, który to stwierdza, zamiast zgłaszać zgodność, której nigdy nie ustalił. Zapisany podpis, który może potwierdzić tylko jego rejestr — we wpisie pliku blokady, którego zapisany w pamięci podręcznej pakiet podpisu został usunięty lub zmieniony — jest pomijany w ten sam sposób, z wierszem wskazującym każdy taki wpis:

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 it

Zapisany podpis, który pull przepisałby niezależnie od odpowiedzi rejestru, jest nadal zgłaszany w trybie offline, ponieważ do jego wykrycia odpowiedź nie jest potrzebna, jak opisano w sekcji Porównuje zapisane podpisy w obu plikach.

Wtyczka dołączona w roli zwracającej werdykt, udostępniana przez rejestr, to punkt, w którym weryfikacja offline i pull offline się rozchodzą. Taka wtyczka nigdy nie jest przypinana w pliku blokady, więc każdy pull rozwiązuje jej .wasm z jej rejestru, a pull w trybie offline dla obszaru roboczego, który ją dołącza, zatrzymuje się w tym miejscu, wskazując wtyczkę jako taką, której .wasm nie mógł rozwiązać — nawet jeśli pamięć podręczna treści ją przechowuje i niezależnie od tego, czy rejestr jest oznaczony jako advisory lub pomija weryfikację podpisów. Weryfikacja offline natomiast o nic rejestru w sprawie wtyczki nie pyta: odczytuje wtyczkę z pamięci podręcznej treści, tak jak robi to build, i zatrzymuje się, jeśli pamięć podręczna nie przechowuje jej .wasm lub przechowuje taki, który nie odpowiada już skrótowi wskazanemu w jej opublikowanym manifeście. Nadal porównuje tożsamość wtyczki z rejestrem zaufania wtyczek i ponownie sprawdza jej funkcje hosta względem tego .wasm, zatrzymując się przy niezgodności którejkolwiek z nich, dokładnie tak jak weryfikacja z połączeniem. Zgłasza wtyczkę tam, gdzie pull przepisuje jej wpis niezależnie od odpowiedzi rejestru, czyli tam, gdzie build odrzuca wtyczkę z powodu jej wpisu: za brak zapisanego podpisu, ponieważ jej wpis go nie zawiera lub rejestr zaufania nie ma dla niej wpisu, albo dlatego, że podpis zapisany we wpisie został złożony dla innego artefaktu, który pull zastępuje własnym podpisem wtyczki. Każdy inny wpis — taki, którego podpis build akceptuje, i taki, którego zapisany w pamięci podręcznej pakiet podpisu został usunięty lub zmieniony — wskazuje w wierszu informującym, że jego podpis nie został sprawdzony, i nie zgłasza niczego na temat tego podpisu:

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 it

Weryfikacja offline przechodzi więc nad wpisem, którego podpis pull z połączeniem zastąpiłby lub usunął — na przykład takim, którego podpisujący został zmieniony ręcznie, albo takim, którego rejestr już nie dołącza — a jedyną informacją o tym jest ten wiersz. Weryfikacja w środowisku odizolowanym pozostaje dostępna; nie mówi jednak, czy referencja od tego czasu się przesunęła ani czy pominięty podpis zostałby ponownie zapisany. Kontrola odczytująca wyłącznie kod wyjścia obejmuje te przypadki tylko wtedy, gdy weryfikacja działa z połączeniem.

Integracja z aggrega build

  • Weryfikacja. aggrega build weryfikuje każdą rozwiązaną zależność względem pliku blokady i zatrzymuje się przy rozbieżności: encja, biblioteka lub plugin, których zawartość nie odpowiada już przypięciu, odwołanie, do którego encja Release teraz sięga, a którego plik blokady nie przypina, lub przypięte, do którego encja Release już nie sięga, a także plik Release edytowany od czasu pobrania. Aby ją usunąć, należy uruchomić aggrega pull --release <release>, polecenie wypisywane przy zatrzymaniu: pobranie rozwiązuje encję Release w jej obecnym stanie, przepisuje przypięcia, które się zmieniły, i zachowuje wszystkie pozostałe, więc nic, czego nie zmieniono, nie przesuwa się. Gdy zmienił się plik w lokalnym źródle encji Recipe, pobranie najpierw wskazuje aggrega pin dla tej encji, jak opisuje Blokada encji. Plik blokady właśnie zapisany przez to polecenie przechodzi tę kontrolę, ponieważ polecenie wykonuje tę samą kontrolę przed zapisem; build, który zatrzymuje się na rozbieżności zaraz po pobraniu, otrzymał inne dane wejściowe niż pobranie — katalog --catalog przekazany jednemu, a drugiemu nie, albo konfigurację obszaru roboczego zmienioną między nimi — dlatego oba należy uruchamiać na tych samych danych. aggrega validate --release i każdy wybór aggrega inspect, który rozwiązuje encję Release, poddają plik blokady tej samej kontroli i odmawiają z tym samym zatrzymaniem, więc żadne z nich nie przepuszcza pliku blokady, który build odrzuca.
  • Automatyczne pobieranie. Jeśli brakuje pliku blokady, a auto_pull ma wartość true, aggrega build najpierw automatycznie uruchamia pobranie. Jeśli auto_pull ma wartość false, czyli domyślną, build zatrzymuje się i prosi o wykonanie pobrania. Pobranie uruchamiane przez build stosuje pin_sources_at_pull, więc przy nieprzypiętej encji zatrzymuje się dokładnie tak jak zwykłe pobranie. Krok pobrania uruchamiany przez build jest tym samym, który opisuje ta strona, więc build uzupełniający istniejący plik blokady zatrzymuje się na przesuniętym ref źródła dokładnie tak jak aggrega pull — zob. Determinizm i integralność.
  • Tryb offline. W trybie offline aggrega build korzysta wyłącznie z tego, co maszyna już posiada, i odmawia dostępu do sieci, zanim zostanie podjęta jakakolwiek próba połączenia. Odwołanie, którego zawartości nie ma w pamięci podręcznej, zatrzymuje build, zamiast powodować błąd w trakcie pobierania, a build bez pliku blokady, który nie ma go uzupełnić, zatrzymuje się, wskazując pobranie, które by go uzupełniło — dokładnie tak jak w trybie online. --auto-pull nie jest odrzucane: uzupełnienie, o które prosi, to pobranie opisane na tej stronie, więc dla encji katalogu już zapisanych w pamięci podręcznej lub obecnych w lokalnym katalogu zapisuje plik blokady bez kontaktu z rejestrem — encja Recipe, której chart jest pobierany ze zdalnego źródła, jest rozwiązywana ponownie, więc w trybie offline zatrzymuje się nawet wtedy, gdy pamięć podręczna zawiera ten chart — a odwołanie, którego nie ma w żadnym z tych miejsc — lub zapisane w pamięci podręcznej, którego wymaganego podpisu plik blokady nie rejestruje albo którego zarejestrowanego podpisu build nie akceptuje — zatrzymuje je odmową samego pobrania, wskazującą to odwołanie. --upgrade jest odrzucane z powodu podanego w sekcji Tryb offline.
  • Wyszukiwanie w katalogach. Pobranie respektuje catalog_dirs z .aggrega-config.yaml nawet bez podania --catalog — a także własne katalogi encji Release, jeśli konfiguracja podaje je w workspace.releases — i rozwiązuje ten sam stos wyszukiwania „pierwszy wygrywa” co aggrega build, więc przypinane zależności odpowiadają temu, co przeszukuje build. Wymieniony katalog, który nie jest katalogiem — na przykład nic tam nie istnieje — jest odrzucany przez oba polecenia, zanim cokolwiek zostanie rozwiązane lub zapisane, ze wskazaniem wpisu oraz pliku konfiguracyjnego i wiersza, które go wymieniają, jak pokazuje Skąd odczytywane są lokalne encje.

Jak rozwiązywanie znajduje dane wejściowe zewnętrzne

Nic w tej sekcji nie zmienia powyższej zasady — nadal istnieje jeden moment, w którym cokolwiek jest przypinane, i jest nim to polecenie. Sekcja opisuje, jak polecenie dociera do trzeciego z trzech rodzajów, co ma znaczenie przy włączaniu rozwiązywania do potoku, odczytywaniu przebiegu, który uległ degradacji, lub zastanawianiu się, dlaczego to polecenie w ogóle renderuje.

Encja katalogu i artefakt źródłowy są wskazane w dokumencie; dane wejściowe zewnętrzne nie są. Rozwiązanie dwóch pierwszych sprowadza się do odczytania tego, co zostało napisane. Dane wejściowe zewnętrzne wskazuje dostawca w trakcie renderowania, a to, jakie adresy URL wskazuje, wynika z renderowanych wartości — brak wpisu w values pozostawia całe poddrzewo schematu chartu nieskompilowane, a każde zdalne odwołanie w tym poddrzewie niezażądane. Żaden odczyt encji Release nie pozwala wyliczyć tego zbioru.

Dlatego polecenie wykonuje dwie rzeczy w jednym przebiegu: rozwiązuje i przypina domknięcie wskazane w dokumentach, a następnie renderuje to domknięcie, aby sprawdzić, o które zdalne dokumenty proszą dostawcy. Wyrenderowane artefakty są odrzucane, a przypięcia zachowywane. Oba kroki są wewnętrzne dla jednego polecenia i żaden nie jest drugim momentem, w którym coś mogłoby zostać przypięte — następuje jeden zapis pliku blokady i zawiera on wszystkie przypięcia.

Warto znać dwie konsekwencje przed włączeniem rozwiązywania do zautomatyzowanego potoku jako taniego kroku. Kosztuje ono więcej niż rozwiązywanie, które tylko odczytuje dokumenty, ponieważ renderuje. Może też zakończyć się niepowodzeniem z powodu, który nie dotyczyłby rozwiązywania opartego wyłącznie na dokumentach: dostawcy, który nie potrafi wyrenderować tej encji Release. W takim przypadku przypięcia zależności są mimo to zapisywane, ponieważ nic w nich nie zależało od renderowania, a komunikat diagnostyczny wskazuje etap, który się zatrzymał, to, co zostało przypięte, oraz to, że kompilacja zostanie zatrzymana ze wskazaniem nieprzypiętego adresu URL. Przebieg nie jest stracony, a sekcja Tryb offline pokazuje ten sam wynik osiągnięty w inny sposób.

Renderowanie poddaje też plik blokady porównaniu, które stosuje kompilacja, zanim cokolwiek zostanie zapisane. Wykonuje ono sekwencję samej kompilacji, więc porównuje plik blokady, który to polecenie ma zapisać, z tym, do czego rozwiązuje się kompilacja tej samej encji Release, dokładnie tak, jak kompilacja porównuje plik blokady znaleziony na dysku. Plik blokady odrzucony przez to porównanie nie jest zapisywany — podobnie jak nic innego, co polecenie zapisałoby po nim — a polecenie zatrzymuje się z komunikatem, że rozwiązywanie i kompilacja nie zgadzają się co do tego, od czego zależy encja Release, po którym następuje każdy wpis wskazany przez porównanie. Nic w plikach użytkownika nie może tego spowodować, a ponowne rozwiązanie doprowadziłoby do tej samej niezgodności, dlatego należy to zgłosić wraz z encją Release zamiast ponawiać próbę. Jest to jedyne niepowodzenie renderowania, które wstrzymuje zapis, i to dzięki niemu kompilacja tej samej encji Release na tych samych danych wejściowych nie zgłasza dryfu w pliku blokady zapisanym przez to polecenie.

Nie ma przełącznika pozwalającego pominąć renderowanie. Taki przełącznik zachowałby jako opcję dokładnie tę niespodziankę, którą eliminuje pojedynczy moment: encję Release, która rozwiązuje się bez błędów, podczas gdy dane wejściowe potrzebne do jej renderowania pozostają nieprzypięte, co wychodzi na jaw dopiero podczas kompilacji.

--auto-pull włącza to samo rozwiązywanie do kompilacji, a kompilacja renderuje raz. Renderowanie wykonywane przy wypełnianiu to to, które znajduje i przypina dane wejściowe zewnętrzne, a kompilacja przedstawia wynik tego renderowania zamiast wykonywać drugie, więc kompilacja jednym poleceniem kosztuje tyle samo renderowania, co zwykła kompilacja na wypełnionym pliku blokady. Strona aggrega build opisuje, które flagi renderowania kompilacji do niego docierają.

Zbiór wynika z parametrów encji Release, tak samo jak zachowują się już przypięcia komponentów. Edycja parametrów encji Release między rozwiązywaniem a kompilacją jest edycją encji Release, więc kompilacja zatrzymuje się przy porównaniu dryfu ze wskazaniem pliku, zanim jakiekolwiek renderowanie mogłoby zażądać nieprzypiętego adresu URL; rozwiązaniem jest to polecenie. Parametry importowane z osobnego pliku nie są rejestrowane według zawartości, więc edycja tego pliku dociera do renderowania, które zatrzymuje się ze wskazaniem nieprzypiętego adresu URL — przy czym wskazane rozwiązanie również wymienia to polecenie.

Determinizm i integralność

Pole source: encji Recipe może szablonować swoją wersję na podstawie rozwiązanych values i infra encji Release (oraz locals zdefiniowanych w tej samej encji); są one rozwiązywane w czasie pull, a wynik jest przypinany. Pull ewaluuje wyłącznie te wpisy locals:, które odczytują pola source:, oraz wpisy odczytywane z kolei przez nie, używając jedynie własnych funkcji pomocniczych szablonów Aggrega: wpis odczytywany przez źródło, który wywołuje funkcję Sprig, zatrzymuje pull, wskazując wpis, pole i funkcję, natomiast wpis, którego nie odczytuje żadne pole source:, pozostaje dla builda, który ewaluuje go i sprawdza podczas renderowania encji Recipe — zob. Resolving a source: coordinate registers a narrower function set (Rozwiązywanie współrzędnej źródła rejestruje węższy zestaw funkcji). Zmienny tag lub gałąź Git jest przypinany do konkretnego commita, na który wskazuje, a utworzona przez autora referencja jest zapisywana obok niego. W czasie builda skrót zbuforowanego archiwum jest ponownie weryfikowany względem pliku blokady, dzięki czemu zmodyfikowana pamięć podręczna zostaje wykryta.

Zapisana referencja jest wiązana z commitem, który przypięła. Referencja jest zapisywana, ponieważ późniejsze przebiegi odpytują ją ponownie, a nie dla czytelności — kompilacja pyta, który artefakt wskazuje, a pobieranie pyta, czy nadal wskazuje to samo miejsce. Polecenie pull, które nie jest aktualizacją, ponownie pyta każdą zapisaną referencję, dokąd wskazuje, a referencja, która przesunęła się w zdalnym repozytorium, zatrzymuje przebieg — ze wskazaniem artefaktu, referencji, commita przypiętego w pliku blokady i commita, do którego rozwiązuje się teraz — zamiast przyjąć tę zmianę. Aby ją przyjąć, należy uruchomić aggrega pull --upgrade --release <release>. Ukierunkowana aktualizacja, która wskazuje identyfikatory URI encji, tego nie robi: odwołanie do źródła nie jest encją, którą można wskazać, więc ukierunkowany przebieg wiąże je dokładnie tak samo jak zwykłe pobieranie.

To sprawdzenie jest jedyną rzeczą, której nie może zapewnić ponowna weryfikacja skrótu podczas kompilacji. Pobieranie, które przyjęłoby przesuniętą referencję, przepisałoby pobrane bajty i zapisany skrót w jednym kroku, więc dwie wartości porównywane przez kompilację zmieniłyby się razem i byłyby zgodne — a kompilowana byłaby inna zawartość źródłowa niż ta, względem której przejrzano plik blokady, i nic by tego nie zgłosiło.

W ten sposób wiązana jest tylko referencja zapisana w pliku blokady, a referencja jest zapisywana za każdym razem, gdy zostanie napisana. Encja Recipe, która wskazuje swoje źródło wyłącznie przez version:, nie ma referencji, więc późniejszy przebieg nie ma czego ponownie odpytywać — i jest to właściwa odpowiedź, ponieważ samodzielnie napisana wersja nie może się nieoczekiwanie zmienić. Dokumentacja pliku blokady określa, co jest zapisywane.

Należy pisać referencję, a nie commit. Polecenie build znajduje artefakt pochodzący z git według napisanej referencji, dopasowanej do referencji zapisanej w pliku blokady, więc ref: v1.2.3 kompiluje się względem commita, do którego przypięto ten tag, a commit nigdy nie musi pojawić się w encji Recipe. Podanie zmiennego tagu w version: nie działa i nie jest do tego przeznaczone: version: jest dopasowywane dosłownie, a dla źródła git plik blokady przypina commit.

Plik blokady przypina zawartość pobraną z rejestrów i źródeł zdalnych oraz zapisuje skrót każdej encji rozwiązywanej z katalogów użytkownika — obejmujący plik encji i każdy plik, który wskazuje obok siebie, jak opisuje sekcja Plik blokady — a także każdego pliku Release odczytanego przez rozwiązywanie. Pliki źródła zaczynającego się od ./ lub ../ oraz plik artefaktu importowany przez encję są również przypinane pojedynczo w blokadzie obok tej encji, jak opisuje sekcja Blokada encji, i to dzięki temu wskazywany jest plik, który się zmienił; za integralność pozostałej części obszaru roboczego między kompilacjami odpowiada system kontroli wersji. Zakres gwarancji determinizmu opisuje strona identyczne bajtowo wyjście.

Uwierzytelnianie

Poświadczenia rejestru są odczytywane wyłącznie z konfiguracji poświadczeń Dockera: config.json w katalogu wskazanym przez DOCKER_CONFIG lub ~/.docker/config.json, gdy ta zmienna nie jest ustawiona, wraz z dowolnym pomocnikiem poświadczeń lub pękiem kluczy systemu operacyjnego, do których plik deleguje przez credsStore lub credHelpers. aggrega login <registry> zapisuje tam poświadczenie, podobnie jak docker login <registry>; jedno z nich należy uruchomić przed aggrega pull w przypadku prywatnego katalogu OCI lub rejestru chartów. Pliki zapisywane przez podman login i helm registry login nie są odczytywane.

Konfiguracja poświadczeń, której nie można odczytać, jest zgłaszana bez ujawniania jej zawartości. Jeśli config.json nie jest prawidłowym JSON-em, wartość auth wpisu nie jest zakodowanym w base64 użytkownikiem i hasłem połączonymi dwukropkiem albo pomocnik poświadczeń wskazany w pliku nie może odpowiedzieć, połączenie z rejestrem kończy się niepowodzeniem z komunikatem wskazującym rejestr i plik poświadczeń, ale nigdy zawartość pliku ani wpisu. aggrega login i aggrega logout zgłaszają w ten sam sposób plik config.json, który nie jest prawidłowym JSON-em, i niczego w nim nie zmieniają. Należy poprawić plik; wpis, którego nie można odczytać, można też zastąpić za pomocą aggrega login <registry>.

Klasyczne repozytorium chartów Helm lub archiwum chartu (helm-https-chart), fragment compose (compose-https-fragment) i repozytorium Git osiągane przez HTTP lub HTTPS (git-repository) uwierzytelniają się za pomocą pliku netrc, czyli pliku poświadczeń użytkownika, który odczytują także curl i Git. To jedyny magazyn poświadczeń odczytywany przez te trzy rodzaje: ~/.config/helm/repositories.yaml i pomocnicy poświadczeń Git nie są odczytywani. Repozytorium Git osiągane przez SSH uwierzytelnia się przez agenta SSH i nie odczytuje żadnego pliku netrc.

machine charts.example.com
login deploy-bot
password <token>

Który plik jest odczytywany. Plik wskazany przez zmienną środowiskową NETRC, gdy jest ustawiona. W przeciwnym razie .netrc w katalogu domowym; w systemie Windows _netrc w %USERPROFILE%, gdy ten plik istnieje, a .netrc w tym samym miejscu, gdy nie istnieje. Brakujący plik nie zawiera poświadczeń i nie jest błędem. Plik, który istnieje, ale nie można go odczytać lub nie ma formatu netrc, zatrzymuje polecenie z E0360, wskazując plik — a przy błędzie formatu także wiersz — ale nigdy jego zawartość: The netrc file cannot be read (Nie można odczytać pliku netrc). W systemach Linux i macOS plik netrc, który mogą odczytać inni użytkownicy maszyny, powoduje jedno ostrzeżenie wskazujące go; należy ustawić go jako czytelny tylko dla siebie (chmod 600).

Który wpis odpowiada na żądanie. Każde żądanie jest wyszukiwane według hosta — nazwy hosta bez portu, bez rozróżniania wielkości liter — i obsługiwane przez pierwszy wpis machine wskazujący ten host lub przez wpis default, gdy żaden go nie wskazuje. login i password wpisu są wysyłane jako poświadczenia uwierzytelniania podstawowego HTTP, zarówno przez http, jak i https; wpis, w którym brakuje któregoś z nich, nie wysyła niczego. Repozytorium, którego indeks umieszcza charty na innym hoście, jest obsługiwane dla każdego żądania osobno: żądanie indeksu bierze wpis hosta repozytorium, a żądanie chartu — wpis hosta chartu. Żądanie wysyłane bez poświadczenia musi być dostępne anonimowo, a serwer odpowiadający 401 lub 403 zatrzymuje pull jako nieautoryzowane pobranie, którego środek zaradczy wskazuje wpis do dodania i plik, w którym go szukano.

Poświadczenie nie jest nigdzie zapisywane. Jest odczytywane podczas pobierania i wysyłane z żądaniem: plik blokady, entity.lock obok encji Recipe, pamięć podręczna źródeł i każdy komunikat zawierają URL źródła w takiej postaci, w jakiej go napisano.

URL źródła nie zawiera poświadczenia. Encja Recipe lub FeatureRecipe, której url źródła zawiera użytkownika przed hostem — https://user:token@charts.example.com/… lub sam token zapisany jako https://token@charts.example.com/… — jest odrzucana z E0361 podczas odczytu dokumentu, zanim cokolwiek zostanie pobrane: walidacja encji Recipe ją odrzuca, podobnie jak każdy pull, pin i build, który do niej dociera. Komunikat wskazuje host, a nigdy poświadczenie: A source URL carries a credential (URL źródła zawiera poświadczenie). Zamiast tego należy umieścić poświadczenie we wpisie machine pliku netrc. W przypadku SSH sam użytkownik — ssh://git@github.com/… — wskazuje konto, a nie sekret, i jest akceptowany, natomiast hasło zapisane w tym miejscu również jest odrzucane.

Kontrola odczytuje tylko część URL przed hostem. Token przekazany w ciągu zapytania lub ścieżce — …/index.yaml?access_token=… — nie jest wykrywany, więc nie należy go tam umieszczać: URL jest zapisywany w postaci, w jakiej go napisano, w pliku blokady, w entity.lock i w pamięci podręcznej źródeł, łącznie z nazwami katalogów pamięci podręcznej.

Zmienne środowiskowe

Ustawienia obszaru roboczego odczytywane przez pull można nadpisać za pomocą środowiska, z pierwszeństwem przed zatwierdzoną konfiguracją i niższym niż jakakolwiek flaga: AGGREGA_OFFLINE (zob. Tryb offline oraz --offline, flagę o wyższym pierwszeństwie), AGGREGA_CATALOG_DIRS (lista rozdzielana separatorem ścieżek systemu operacyjnego; należy podawać ścieżki bezwzględne), AGGREGA_ARTIFACT_CACHE_DIR, AGGREGA_DEFAULT_REGISTRY oraz AGGREGA_SKIP_SIGNATURE_VERIFICATION (głośna — wszędzie tam, gdzie pull sprawdziłby podpis, zapisuje w logu ostrzeżenie, że weryfikacja jest globalnie wyłączona). Pełna lista i model pierwszeństwa znajdują się w environment-variables.md.

Zobacz także

  • ./aggrega-build.md — weryfikuje plik blokady i automatycznie wykonuje pull, gdy jest to skonfigurowane.
  • ./aggrega-serve.md — demon udostępnia to samo rozwiązywanie zależności pod aggrega/resolveDependencies oraz wewnątrz aggrega/build dla żądania, którego pole autoPull tego wymaga, dzięki czemu edytor może je uruchomić bez opuszczania sesji; w obu przypadkach działa ono tylko wtedy, gdy żądanie je wskazuje, i zapisuje ten sam plik blokady co to polecenie.
  • ./aggrega-push.md — publikuje encje katalogu w rejestrze.
  • ./aggrega-lint.md — bramka publikacji poprzedzająca aggrega push.
  • ../../architecture/13-catalog-and-registry.md — pełny opis modelu katalogu, pliku blokady i pamięci podręcznej.

Składnia

aggrega pull [<uri>...] [flags]

Opis

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 honoring
the pins it already records. That pin discipline governs what a registry or the content cache
serves: 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 the
version its file declares, and its recorded pin is not consulted — so editing a pin by hand does
not hold a locally-supplied entity at that version, and the reconcile rewrites the entry to match
the file. A reference with no pin — newly added, or removed from the lockfile by hand — is
resolved 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-resolve
every entity from current registry state, floating each dependency to the highest available
version. That form drops every recorded pin, so it asks for confirmation first; --yes answers in
advance, and on a non-interactive stdin it refuses rather than waiting for an answer nobody can
give. Pass one or more entity URIs after --upgrade to upgrade only those: each named pin
is 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 the
workspace no longer attaches drops its recorded identity — the one way to clear an entry that
outlived 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 carries
the 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 the
entity author's step, aggrega pin.
By default pull records none of them, and halts on an entity whose lock is missing any, naming
the entity, each input and its class, and the command that records them. A local source's files
are held to their pins as one set: a file added, changed or removed since the pin halts the pull
the same way.
Pass --pin-sources, or set pin_sources_at_pull in the workspace configuration, to have pull run
that 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 was
pinned, by the ignore rules of the plugin that served its capability for the author, and its
entity.lock records that decision. Where the plugin this workspace binds for that capability
declares different rules, pull prints a warning naming both plugins and the difference, and
carries on: the entity's files are the ones its recorded rules kept.

Flagi

FlagaDomyślnieOpis
--catalog[]Katalog z katalogiem encji; można podać wielokrotnie. Każde —catalog <dir> jest dodawane na początek stosu wyszukiwania katalogów (wygrywa pierwsze dopasowanie): catalog_dirs obszaru roboczego lub — dla encji Release, której konfiguracja obszaru roboczego nadaje własne katalogi w workspace.releases — katalogi tej encji Release; stos kończy się katalogiem o nazwie catalog w katalogu głównym obszaru roboczego, jeśli taki istnieje. Lista catalog_dirs zapisana jako pusta oznacza, że żaden lokalny katalog nie jest odczytywany.
--detailfalseWypisuje dla każdej rozwiązanej encji, co zrobił ten pull — pobrał ją na nowo z rejestru, ponownie użył slotu pamięci podręcznej, znalazł ją w lokalnym katalogu, dostarczył ją z wnętrza pliku binarnego kompilatora lub uznał za zewnętrzną (własna encja Aggregate lub Manifest encji Release, odczytana z pliku lub wpisu, który wskazuje encja Release). Tylko stdout; nie jest zapisywane w pliku blokady
--dry-runfalseRozwiązuje zależności i wypisuje, co ten pull by zapisał, zamiast to zapisywać: ścieżka każdego pliku i treść, którą by zawierał, trafiają na stdout, a plik blokady, entity.lock obok każdej encji Recipe i FeatureRecipe, której zapisane przypięcia zmieniłyby się przy —pin-sources, oraz rekord zaufania pluginów pozostają nietknięte. Wymieniane są tylko pliki, które faktycznie by się zmieniły. Samo rozwiązywanie przebiega dokładnie tak jak zwykle, więc pamięć podręczna treści nadal się zapełnia, pull, który zatrzymałby się na nieprzypiętej encji, zatrzymuje się także tutaj, a samo —upgrade o nic nie pyta, ponieważ nie usuwa żadnego przypięcia — to, co pokazuje przebieg próbny, jest tym, co zapisałby pull. Nieakceptowane razem z —verify, które i tak żadnego z nich nie zapisuje
--include-prereleasefalseJeszcze niezaimplementowane: akceptowane i ignorowane, dzięki czemu skrypt, który je przekazuje, będzie nadal działał, gdy zacznie ono mieć efekt
--pin-sourcesfalseWykonuje krok przypinania autora encji dla encji Recipes i FeatureRecipes budowanych przez tę encję Release, zapisując w entity.lock obok każdej z nich przypięcie dla każdego odczytywanego wejścia — zdalnego source: zapisanego w całości, pliku importowanego przez wpis artifacts oraz każdego pliku lokalnego źródła — zamiast zatrzymywać się na encji, której blokada ich nie zapisuje. Ten sam krok co aggrega pin, zapisujący te same bajty. Zapisuje obok encji, więc działa tylko tam, gdzie encja ma zapisywalne miejsce: dokument w jednym z katalogów z katalogiem encji. Encja rozwiązana z pamięci podręcznej go nie ma i nigdy nie jest przypinana. Nadpisuje ustawienie pin_sources_at_pull obszaru roboczego w obu kierunkach: —pin-sources przypina w tym przebiegu, a —pin-sources=false zatrzymuje w tym przebiegu, niezależnie od ustawienia
--progressfalseWymusza włączenie wskaźnika postępu pull, nawet gdy stderr nie jest terminalem, wypisując jeden zwykły wiersz na każdy ukończony krok wraz z jego czasem. Domyślnie auto: interaktywna lista faz jest pokazywana tylko wtedy, gdy stderr jest terminalem interpretującym sekwencje sterujące, terminal, który ich nie interpretuje, otrzymuje te same zwykłe wiersze, a wyjście przekierowane lub potokowe nie otrzymuje żadnych
--quietfalseWycisza wskaźnik postępu pull na stderr. Nie wpływa na stdout. Ma pierwszeństwo przed —progress
--release—Ścieżka do pliku YAML encji Release (wymagana). Ścieżka względna jest rozwiązywana względem katalogu, w którym uruchamiane jest polecenie, a nie względem katalogu głównego obszaru roboczego. Gdy ten katalog nie należy do żadnego obszaru roboczego i nie wskazano katalogu głównego, ścieżka bezwzględna odnajduje obszar roboczy na podstawie własnego folderu encji Release
--upgradefalsePonownie rozwiązuje zależności według bieżącego stanu rejestru, podnosząc każdą do najwyższej dostępnej wersji. Bez argumentów (bez pozycyjnych URI) odrzuca plik blokady i ponownie rozwiązuje każdą encję, a najpierw prosi o potwierdzenie, ponieważ usuwa każde zapisane przypięcie; z jednym lub kilkoma URI encji ponownie rozwiązuje tylko je, pozostawiając wszystkie inne przypięcia i zapisane wejścia zewnętrzne bez zmian, i o nic nie pyta (wzajemnie wykluczające się z —verify)
--verifyfalseWeryfikuje istniejący plik blokady względem rozwiązania zależności, które pull wykonałby teraz, bez zapisywania pliku blokady, rekordu zaufania pluginów ani żadnego entity.lock; kończy się kodem niezerowym przy rozbieżności lub braku pliku blokady. Rozwiązywanie respektuje przypięcia zapisane w pliku blokady dokładnie tak jak pull: odwołanie, którego rejestr opublikował nowszą wersję od czasu pull, nie jest rozbieżnością, ponieważ pull utrzymałby jego przypięcie, a rejestr serwujący teraz inne bajty pod przypiętą wersją zatrzymuje weryfikację tak, jak zatrzymuje pull. Pamięć podręczna treści jest odczytywana i zapełniana tak, jak robi to pull: wpis, który pamięć podręczna przechowuje pod jego przypięciem, jest odczytywany stamtąd bez odpytywania rejestru, wpis, którego nie przechowuje, jest pobierany, a wpis, który nie odpowiada już swojemu przypięciu, jest traktowany dokładnie tak, jak traktuje go pull. Ponadto sprawdza entity.lock obok każdej encji Recipe i FeatureRecipe w katalogach z katalogiem encji, do której sięga encja Release, względem tego, z czym porównuje go build, i kończy się kodem niezerowym przy przypięciu, które build by odrzucił: importowanym pliku, który nie odpowiada już zapisanemu skrótowi, lokalnym źródle, którego pliki nie odpowiadają już zapisanym skrótom, lub przypięciu źródła niezgodnym z plikiem blokady. Ponadto porównuje podpis zapisany w pliku blokady dla każdego artefaktu oraz rekord zaufania pluginów dla każdego pluginu z tym, który pull zapisałby teraz, i kończy się kodem niezerowym tam, gdzie pull zapisałby, zastąpił lub usunął któryś z nich: podpis wymagany przez wymaganie, który nie jest zapisany, oraz podpis wykonany dla innego artefaktu są zgłaszane bez odpytywania rejestru, ponieważ pull przepisuje je niezależnie od odpowiedzi; o podpis, który pull wyszukuje ponownie i mógłby zapisać bez zmian — artefakt został pobrany albo jego zbuforowany pakiet podpisu został usunięty lub zmieniony — odpytywany jest jego rejestr, a w trybie offline pozostaje niesprawdzony, co sygnalizuje odpowiedni wiersz; każdy plugin objęty rekordem zaufania pluginów jest weryfikowany w swoim rejestrze, tak jak weryfikuje go każdy pull, z wyjątkiem trybu offline, w którym jest odczytywany z pamięci podręcznej treści tak, jak odczytuje go build, jego tożsamość i funkcje hosta są nadal sprawdzane, a jego podpis pozostaje niesprawdzony, co sygnalizuje odpowiedni wiersz, chyba że build odrzuca go z powodu braku zapisanego podpisu lub podpisu wykonanego dla innego artefaktu, co jest zgłaszane. Znaczniki wycofania nie są porównywane. Ponadto zgłasza wersje kompilatora i pluginów rdzenia zapisane w pliku blokady — zgłaszane na potrzeby audytu i nigdy nieporównywane z tym plikiem binarnym, więc różnica w narzędziach nigdy nie jest rozbieżnością. Nieakceptowane razem z —pin-sources, niezależnie od podanej wartości: weryfikacja ani nie zapisuje przypięcia, którego brakuje w entity.lock, ani się na nim nie zatrzymuje, więc flaga niczego by nie zmieniła (wzajemnie wykluczające się z —upgrade)
--yesfalseUdziela z góry odpowiedzi na potwierdzenie samego —upgrade, do użytku nieinteraktywnego. Dotyczy tylko tego jednego monitu: każda inna forma pull o nic nie pyta, więc przekazanie tej flagi niczego tam nie zmienia