aggrega pull
aggrega pull phân giải mọi phụ thuộc của một Release và ghi một lockfile ghim từng phụ thuộc vào một phiên bản và một content digest chính xác. Một lần aggrega build sau đó sẽ dùng những gì lockfile ghim, xác minh chúng, và dừng lại, nêu tên bất kỳ thứ gì nó cần mà không được ghim ở đó — nhờ vậy các bản build có thể tái tạo được và có thể chạy ngoại tuyến.
Mọi thứ một bản build sử dụng đều được ghim tại đúng một thời điểm này. Các thực thể catalog, các artifact nguồn mà một Recipe trỏ một provider tới, và các tài liệu từ xa mà một provider yêu cầu trong lúc render đều được phân giải bởi cùng một lệnh và được ghi lại trong cùng một lần ghi lockfile. aggrega pull là bước truy cập mạng; build thì không. Đó là toàn bộ quy tắc, và phần còn lại của trang này là những gì suy ra từ nó.
Chức năng
aggrega pull phân giải ba loại phụ thuộc trong một lượt:
- Các thực thể catalog — các Components, Features, Recipes, FeatureRecipes, thư viện schema và mapping, và các plugin Wasm mà Release tham chiếu, được phân giải bắc cầu (qua
extends:,implements:,aggregate:, các gắn kết Feature, và các vị trí$import:/$ref:của thư viện) và được tải về từ registry khi chưa có sẵn cục bộ. - Các artifact nguồn —
source:từ xa mà một Recipe hoặc FeatureRecipe riêng lẻ trỏ một provider tới: một Helm chart (OCI hoặc HTTPS cổ điển) hoặc một đoạn Compose qua HTTPS. Mỗi artifact được tải về, lưu cache và ghim. - Các đầu vào bên ngoài — các tài liệu từ xa mà một provider yêu cầu host cung cấp trong khi render, chẳng hạn một
$reftrongvalues.schema.jsoncủa một chart trỏ tới một URL. Mỗi tài liệu được tải về, lưu theo digest nội dung của nó, và ghim.
Hai trong ba loại được đọc ra từ các tài liệu bạn viết. Loại thứ ba thì không: các đầu vào bên ngoài được tìm thấy bằng cách render Release, đó là lý do lệnh này render một Release. Việc chạy lệnh không cần biết điều đó — Cách quá trình phân giải tìm các đầu vào bên ngoài trình bày đầy đủ, cùng với chi phí của lần render, điều gì xảy ra khi nó không thể hoàn tất, và một bản build tự điền lockfile của mình liên quan đến nó như thế nào.
Một thực thể catalog được nêu tên mà không kèm registry sẽ được tải về qua default_registry của workspace, và đường dẫn repository mà giá trị mặc định mang theo là nơi nó được tải về. Với default_registry: ghcr.io/acme, core/api-server được tải về từ ghcr.io/acme/component/core/api-server — nơi aggrega push xuất bản nó qua cùng giá trị mặc định đó — và chữ ký của nó được tìm ở đó. Đường dẫn chỉ là vị trí: chữ ký mà một lần pull yêu cầu, các khóa và danh tính mà nó tin cậy, và thông tin xác thực mà nó xuất trình là những thứ được lưu cho host, vì vậy mục registries cho ghcr.io chi phối mọi đường dẫn trên host đó. Lockfile ghi nhận một thực thể như vậy theo danh tính, phiên bản và các digest của nó, giống như ghi nhận một thực thể được tải về chỉ từ một host. Cách viết một đường dẫn được trình bày trong cách viết một host registry.
Lệnh ghi kết quả vào <release-stem>.lock bên cạnh Release. Một workspace gắn một plugin trả về phán quyết chấp nhận hoặc từ chối cũng nhận thêm một tệp thứ hai trong thư mục đó — bản ghi tin cậy plugin.
Một lần pull được yêu cầu ghim sẽ ghi thêm một loại tệp. Bên cạnh mỗi Recipe và FeatureRecipe trong các thư mục catalog của bạn mà import một tệp artifact, trỏ tới một source: từ xa do bạn viết đầy đủ, hoặc đọc một source: bên cạnh nó, có một entity.lock ghi lại digest của nội dung đó. Việc ghi lại là bước của tác giả thực thể, aggrega pin, và theo mặc định một lần pull không làm việc này: nó đối chiếu lock của mỗi thực thể như vậy với những gì bước đó sẽ ghi, và dừng lại ở nơi thiếu một pin. aggrega pull --pin-sources, hoặc một workspace đặt pin_sources_at_pull: true, sẽ chạy bước đó thay thế — và khi đó tác động của một lần pull vươn xa hơn thư mục chứa Release, dù các tệp thực thể bạn viết không bao giờ bị ghi đè. Entity lock mô tả tệp đó, và Xem trước những gì một lần pull sẽ ghi cho thấy toàn bộ tập tệp cho workspace của bạn trước khi có bất kỳ thay đổi nào.
Một lần pull bị từ chối vì một tham chiếu không phân giải được thành gì cả sẽ cho biết các thực thể cục bộ được đọc từ đâu, bất kể nó chạy ở đâu. Thông báo từ chối mang theo mô tả của chính workspace về các thư mục mà nó đã đọc thực thể cục bộ và những gì cần thay đổi để thực thể được đọc — như ghi chú Nơi các thực thể cục bộ được đọc cho thấy — và nó mang theo điều đó từ lệnh này, từ một bản build phân giải các phụ thuộc trước, từ công cụ pull của aggrega mcp và từ quá trình phân giải phụ thuộc của một trình soạn thảo như nhau, vì quá trình phân giải mà tất cả chúng chạy đều tạo ra nó. Thông báo từ chối của công cụ pull cũng nêu mã ngắn và mã mô tả của tình trạng, giống như một terminal in mã ngắn ở đầu thông báo từ chối. Một tệp trong các thư mục đó khai báo một apiVersion của Aggrega — một dòng bắt đầu, không thụt lề, bằng apiVersion: và một giá trị bắt đầu bằng aggrega.ai/ — và không thể nạp được, chẳng hạn một tệp không phân tích được dưới dạng YAML, sẽ được nêu tên trong cùng thông báo từ chối, trong số các tệp catalog bị bỏ qua khi nạp, kèm lý do của chính bộ phân tích cú pháp: một tệp như vậy có thể chính là tệp khai báo thực thể mà tham chiếu nêu tên, và không thể đọc được gì từ nó để biết nó khai báo thực thể nào. Một tệp YAML khai báo một apiVersion khác, hoặc không khai báo apiVersion nào, không phải là tài liệu Aggrega và không bao giờ được nêu tên ở đó.
Tệp khóa
Tệp khóa ghim mỗi phụ thuộc vào URI, phiên bản đã phân giải và digest nội dung của nó. Tệp có các phần cho các thực thể catalog, các thư viện schema và mapping (mỗi thư viện mang con trỏ ngược tới các Components và Features sử dụng nó), các plugin Wasm, các artifact nguồn, các đầu vào bên ngoài (mỗi đầu vào được khóa theo URL và mang các plugin đã yêu cầu nó), và chính các tệp Release. Tệp được ghi ở dạng chuẩn tắc, tất định.
Một thực thể được ghi nhận theo những gì một bản phát hành của nó mang theo. Digest trong hàng của một thực thể bao gồm tài liệu của nó và mọi tệp mà nó nêu tên bên cạnh nó — source: cục bộ của một Recipe hoặc FeatureRecipe, mỗi tệp mà một $import: nêu tên, entity.lock bên cạnh nó, mỗi tệp schema mà một Component hoặc Feature nhập vào — cùng tập hợp mà aggrega push xuất bản. Mỗi tệp đóng góp đường dẫn và các byte của nó, và không có gì khác đóng góp: không phải cách một archive được nén, không phải dấu thời gian, không phải bit quyền, kể cả bit thực thi. Một thực thể không nêu tên tệp nào được ghi nhận là chính tài liệu đó. Vì vậy, cùng một thực thể ghi nhận cùng một digest dù nó được đọc từ thư mục catalog của bạn hay được tải từ một registry, và một tệp khóa được commit từ một checkout sẽ xác minh được trên một checkout khác của cùng commit bất kể umask của nó, và bất kể hệ thống của checkout đó có ghi nhận tệp nào là thực thi được hay không. Một chart được chỉnh sửa dưới một Recipe, một tệp được thêm vào một nguồn mà nó khai báo và một entity.lock bị thay đổi đều làm thay đổi digest; một script bị lật bit thực thi, và một ghi chú bên cạnh thực thể mà không gì nêu tên, thì không. Aggregate và Manifest mà Release nêu tên được ghi nhận theo cùng cách, mỗi cái là một tài liệu của nó. Một thư viện được ghi nhận theo digest các byte của nó, chính là tài liệu của nó dù được đọc từ đâu.
Mỗi Recipe và FeatureRecipe mà Manifest ràng buộc là một hàng, bất kể tầng nào ràng buộc nó. Một hiện thực hóa mà tầng name của Manifest chọn cho một instance hoặc một attachment được thu nhận và ghi nhận giống hệt như một hiện thực hóa mà tầng type của nó chọn cho mọi instance của một kiểu, và referenced_from của hàng đó nêu tên mục ràng buộc nó — manifest.spec.mappings.components.name.<instance> hoặc manifest.spec.mappings.features.name.<attachment>. Một bản build giữ nó đúng với hàng đó, nên một tệp khóa không ghi nhận nó sẽ dừng bản build, nêu tên hiện thực hóa và mục đó. Xem Ánh xạ URI phẳng để biết về hai tầng.
Các attachment của một kết nối là phụ thuộc giống hệt như các attachment của chính một component. Feature mà một attachment trên một kết nối nêu tên — được viết trên mục uses: của một component trong Aggregate, hoặc trên một mục kết nối trong Release — được thu nhận và ghi nhận như Feature của một attachment được viết trên chính component, và referenced_from của hàng đó nêu tên mục kết nối mà tác giả đã viết, kết thúc bằng .uses.<socket>.<alias>.features.<slot>.type. Hiện thực hóa mà Manifest ràng buộc vào nó cũng là một hàng, dù features.type ràng buộc nó hay features.name được khóa theo tên của attachment, <alias>.<slot>. Một bản build giữ cả hai đúng với các hàng của chúng: một tệp khóa thiếu một trong hai sẽ dừng bản build, nêu tên tham chiếu và mục yêu cầu nó, và một Feature có nội dung đã thay đổi kể từ lần pull sẽ dừng bản build, nêu tên cả hai digest. Xem mục kết nối của Aggregate để biết về chính attachment.
Một thực thể cơ sở mà một Component hoặc Feature mở rộng là một hàng, dù có thứ gì khác nêu tên nó hay không. Lần pull đi theo từng extends: đến cuối chuỗi của nó và ghi lại mọi thực thể cơ sở dưới loại riêng của nó, với referenced_from của hàng đó nêu tên spec.extends của thực thể mở rộng — component(<name>:<version>).spec.extends. Một bản build đọc thực thể cơ sở từ hàng đó, nên một Manifest ánh xạ kiểu riêng của một wrapper và không cần dòng nào cho thực thể cơ sở của nó. Một thực thể cơ sở mà không thư mục catalog, bộ nhớ đệm hay registry nào chứa sẽ được báo cáo tại nơi chuỗi được hợp nhất — xem An extends: chain cannot be assembled (Không thể lắp ráp một chuỗi).
Release được ghi nhận theo nội dung của nó, không chỉ theo tên. Mọi thứ Release yêu cầu — một nguồn phân giải tới phiên bản chart nào, các component nào nằm trong boundary nào — đều được phân giải từ những gì tệp chứa, nên release_documents ghi nhận digest của Release và của mỗi Release mà nó mở rộng, cùng với release, trường nêu tên nó. Chỉnh sửa Release sau khi pull thì bản build tiếp theo sẽ dừng trước khi bất cứ thứ gì được render, nêu tên tệp bạn đã chỉnh sửa và yêu cầu bạn pull lại; một lệnh aggrega pull --release <release> đơn thuần ghi nhận chỉnh sửa đó trong khi vẫn tôn trọng mọi ghim khác. Digest bao gồm các byte của tệp đúng như chúng là, nên một thay đổi về chú thích hay khoảng trắng cũng được tính, giống hệt như đối với Aggregate và Manifest. Một tệp mà Release nhập vào thông qua parameters không được ghi nhận theo cách này.
Một lần pull tìm dấu ngừng hỗ trợ trên mọi artifact mà nó kiểm tra chữ ký, và cho biết những gì nó tìm thấy. Một dấu có chữ ký riêng được xác minh với một người ký mà lần pull công nhận — người ký của chính artifact, hoặc một danh tính trong trusted_deprecation_identities của registry — sẽ được ghi nhận, và được thông báo kèm mức độ nghiêm trọng và người ký của dấu đó. Một dấu mà lần pull tìm thấy nhưng không thể công nhận — không đọc được, chưa ký, được ký bởi người mà chính sách không tin cậy, hoặc mang một chữ ký không thể kiểm tra — được báo cáo là marker present but not honored, kèm lý do, và không được ghi nhận. Một lần tra cứu không thể hoàn tất — lần pull không mở được registry của artifact, hoặc danh sách những gì được đính kèm vào nó không phản hồi — được báo cáo là marker lookup did not complete, kèm lý do, và không ghi nhận gì, vì lần pull không biết được gì về việc có tồn tại dấu hay không. Với một registry mà chính sách tin cậy riêng của nó yêu cầu chữ ký cho loại của artifact và không phải là advisory, bất kỳ trường hợp nào trong hai trường hợp đó sẽ dừng lần pull thay vì được báo cáo. Một artifact không mang dấu nào không tạo ra dòng nào, và ở nơi việc xác minh chữ ký bị tắt, cho workspace hoặc cho registry của artifact, sẽ không có dấu nào được tìm.
Hãy commit <release-stem>.lock cùng với Release, như cách bạn commit bất kỳ manifest phụ thuộc đã ghim nào. Một diff của tệp khóa cho người review thấy chính xác phiên bản và digest phụ thuộc nào đã thay đổi; một thay đổi digest của thư viện nêu tên các bên sử dụng mà nó ảnh hưởng.
Những gì một lần pull cụ thể đã làm — mỗi thực thể được tải mới từ một registry (fetched-fresh), dùng lại một ô cache (cache-reuse), được tìm thấy trong một catalog cục bộ (local), được phục vụ từ bản sao bên trong binary của trình biên dịch (in-binary), hay là bên ngoài (external: Aggregate hoặc Manifest của chính Release, được đọc từ tệp hoặc mục mà Release nêu tên thay vì được phân giải như một trong các phụ thuộc của nó; một Aggregate mà lần pull tải từ một registry thì thay vào đó là fetched-fresh) — là một chẩn đoán sự kiện pull tạm thời được in ra stdout bởi --detail, và nó không bao giờ được ghi vào tệp khóa. Nguồn nào phục vụ một thực thể phụ thuộc vào trạng thái cục bộ của máy thực hiện pull, nên việc lưu lại nó sẽ phá vỡ tính đồng nhất từng byte của tệp khóa giữa các máy. Nó báo cáo những gì lần pull này đã làm, điều không thể khôi phục sau đó (một thực thể vừa được pull sẽ được cache ở lần chạy tiếp theo); để xem trạng thái phân giải sau pull của các phụ thuộc của một Release, hãy dùng aggrega inspect.
Khóa thực thể
Một Recipe hoặc FeatureRecipe có thể phụ thuộc vào các byte nằm ngoài tài liệu của chính nó: một chart hoặc fragment được tải từ một source: từ xa, một tệp mà một mục artifacts — hoặc một mục trong boundary.artifacts của một Recipe — đưa vào bằng $import, hoặc các tệp của một source: chỉ đến một thư mục hoặc một tệp nằm cạnh nó. Digest của từng thứ đó được ghi vào một tệp tên là entity.lock, trong cùng thư mục với tệp thực thể. Tệp thực thể bạn viết không bao giờ bị ghi đè; những gì được suy ra nằm cạnh nó. Lược đồ khóa thực thể mô tả tệp này theo từng trường.
Ai ghi nó. Một bước ghi nó: aggrega pin, do tác giả của thực thể chạy, không cần Release nào, và ghi mọi loại pin mà khóa chứa. aggrega pull --pin-sources và aggrega push --pin-sources chạy chính bước đó thay cho tác giả và ghi ra cùng các byte. Một lần pull không được yêu cầu pin sẽ không ghi khóa nào: với mỗi Recipe và FeatureRecipe mà Release xây dựng từ các thư mục catalog của bạn, nó so sánh những gì bước đó sẽ ghi với những gì khóa đang chứa, và dừng lại ở chỗ một pin bị thiếu hoặc không còn khớp với đầu vào của nó, nêu tên thực thể, từng đầu vào và loại của nó, cùng aggrega pin. Các tệp của một nguồn cục bộ được đối chiếu với các pin của chúng như một tập hợp: một khóa không ghi tệp nào trong số đó sẽ làm dừng lần pull, và một tệp được thêm, thay đổi hoặc xóa kể từ lần pin cũng vậy. Khóa workspace pin_sources_at_pull biến việc pin thành mặc định của mọi lần pull, và --pin-sources=false khôi phục việc dừng cho một lần chạy. Pin là trách nhiệm của tác giả, nên việc dừng ở lần pull đầu tiên của người dùng có nghĩa là bên phát hành thực thể chưa bao giờ pin nó; cách khắc phục của người dùng là khóa đó chứ không phải sửa tay thư mục của người khác. aggrega pin trình bày đầy đủ điều này.
Nó chứa gì. Ba danh sách, mỗi hàng nêu một đầu vào:
sourceDigests— một hàng cho mỗisource:từ xa mà bạn viết đầy đủ tọa độ, không có template trongkind,url,chart,module_subdir,versionhoặcrefcủa nó. Hàng này chứakindvàurlcủa nguồn,charthoặcmodule_subdirnếu có, phiên bản mà nó phân giải tới — với nguồn git, là commit màrefcủa nó chỉ đến — và digest nội dung của archive đã tải, cộng thêm digest manifest đối với chart được tải qua OCI.artifactDigests— một hàng cho mỗi mụcartifactshoặcboundary.artifactsđược cung cấp bởi một tệp nhập bằng$import, nêu tên mục và digest các byte của tệp. Một mụcartifactsđược gọi theo khóa của nó, còn một mụcboundary.artifactstheo dạngboundary/<key>, nên mục của mỗi khối viết dưới cùng một khóa được pin riêng.localSourceDigests— một hàng cho mỗi tệp mà mộtsource:chỉ đến một thư mục hoặc một tệp cạnh thực thể góp vào những gì một bản phát hành của thực thể mang theo, nêu đường dẫn của tệp bên cạnh thực thể và digest các byte của nó. Không có gì được tải cho nguồn như vậy; các tệp của nó được tính digest theo nguyên trạng. Một nguồn viết dưới dạng template góp mọi tệp trong thư mục của thực thể, nên mỗi tệp đó có một hàng.
Những gì nó không chứa:
- Một nguồn từ xa có tọa độ được điền từ template — chẳng hạn một
versionđọc từ.infra. Artifact mà nó chỉ đến do mỗi Release sử dụng thực thể quyết định, nên mỗi phiên bản nó phân giải tới được pin trong lockfile của Release đó, và không có gì về nó được ghi cạnh thực thể. - Một mục
artifactshoặcboundary.artifactsnội tuyến, vốn là một phần của tệp thực thể, và một mục lấy từ một ArtifactLibrary, có nội dung được pin bởi phiên bản thư viện mà lockfile ghi lại.
Một thực thể không có gì để pin sẽ không có entity.lock, và bước này, khi chạy trên một thực thể không còn cần khóa, sẽ xóa nó.
Commit nó cạnh thực thể. Mọi Recipe và FeatureRecipe dùng cùng một tên tệp, và thư mục chứa nó cho biết nó thuộc về thực thể nào, nên khóa đi cùng thư mục đó. Nó không mang timestamp và các hàng được giữ theo thứ tự cố định, nên bước này trên các đầu vào không đổi để nó giống hệt từng byte, và một diff trên nó nêu ra nguồn, tệp được nhập hoặc tệp của nguồn cục bộ đã thay đổi. Một thư mục chứa một khóa, nên bước này từ chối một Recipe hoặc FeatureRecipe có bất kỳ thực thể nào khác bên cạnh — mọi kind đều có thư mục riêng trừ Aggregate, Release và Manifest — và một lần pull được yêu cầu pin sẽ từ chối thực thể như vậy trước khi phân giải bất cứ thứ gì; Một thực thể mỗi thư mục trình bày quy tắc này. Một lần pull không pin không ghi gì cạnh thực thể và không đánh giá thư mục của nó.
aggrega build đối chiếu các tệp của bạn với nó. Một lần build đọc khóa và thực hiện ba phép so sánh:
- Mỗi tệp được nhập được tính digest lại và so sánh với hàng của nó, tệp
boundary.artifactscũng như tệpartifacts. Một tệp bị sửa sau khi được pin sẽ dừng build với[CATALOG_ERROR E0026], nêu tên artifact như hàng của nó ghi, tệp được nhập và cả hai digest. - Các tệp của một nguồn cục bộ được tính digest lại và so sánh với các hàng của chúng, như một tập hợp, trước khi provider đọc nguồn. Một tệp bị sửa, thêm hoặc xóa kể từ lần pin sẽ dừng build với
E0305dưới instance component sở hữu nguồn đó, nêu từng tệp như vậy và cả hai digest; một tệp cạnh thực thể mà nguồn không góp vào thì không được so sánh. Một khóa không ghi hàng nào cho một nguồn cục bộ thì không có gì để so sánh, như A local source no longer matches the pins recorded beside its Recipe (Một nguồn cục bộ không còn khớp với các pin được ghi cạnh Recipe của nó) mô tả. - Mỗi hàng nguồn được so sánh với digest mà lockfile của Release ghi cho cùng nguồn đó. Sự không khớp sẽ dừng build với
[FETCH_ERROR E0135], nêu tên khóa và cả hai digest. Hai tệp được ghi bởi hai lần phân giải cùng một nguồn — của bước pin và của lần pull — nên chúng không khớp khi hai lần phân giải đó nhận được các byte khác nhau, hoặc khi một trong hai tệp bị sửa. Các byte khác nhau dưới cùng một phiên bản là dấu hiệu của một upstream đã phát hành lại một phiên bản.
Một lockfile được ghi trước thay đổi sẽ dừng trước, và một lần pull nêu tên tệp. Lockfile ghi thực thể theo những gì nó mang theo, và khóa cùng mọi tệp mà các phép so sánh này đọc là một phần của đó, nên một lần build — hoặc aggrega pull --verify — giữ một lockfile được ghi trước khi một tệp được nhập, một tệp của nguồn cục bộ hoặc chính khóa thay đổi sẽ dừng trước khi bất kỳ phép so sánh nào trong ba phép chạy: The lockfile no longer matches what the release resolves to (Lockfile không còn khớp với những gì release phân giải tới), nêu tên thực thể và cả hai digest. Khi đó một aggrega pull thông thường sẽ nêu tên tệp, vì nó đối chiếu khóa với những gì bước pin sẽ ghi và từ chối đầu vào có pin không còn khớp: An entity reads an input the lock beside it records no pin for (Một thực thể đọc một đầu vào mà khóa bên cạnh nó không ghi pin).
Khi lockfile không ghi nội dung riêng của thực thể, ba phép so sánh là những gì một lần build gặp phải. Một Recipe hoặc FeatureRecipe mà Manifest gọi bằng một tham chiếu cũng là tên của một Component hoặc Feature mà Release dẫn tới thì không có mục riêng: mục của lockfile cho tham chiếu đó ghi Component hoặc Feature, nên không có gì trong lockfile thay đổi khi các tệp của Recipe thay đổi, và một lần build cũng như một lần pull kiểm tra sẽ báo tệp đã thay đổi với mã ở trên. Phép so sánh hàng nguồn cũng là những gì một lần build gặp khi mục source_artifacts của lockfile là bản ghi đã thay đổi trong khi khóa cạnh thực thể thì không.
Xử lý lần dừng. Nếu bạn cố ý thay đổi tệp được import, hãy chạy aggrega pin trên thực thể: bước này ghi lại digest mới của tệp, và lần build tiếp theo sẽ chấp nhận nó. Nếu bạn không cố ý, hãy khôi phục tệp. Một nguồn cục bộ đã thay đổi cũng có hai cách xử lý như vậy: pin lại thực thể, hoặc khôi phục các tệp mà lần dừng nêu tên. Với một hàng nguồn không khớp với lockfile, hãy khôi phục entity.lock từ hệ thống quản lý phiên bản, hoặc chạy aggrega pin trên thực thể để ghi lại nó.
aggrega pull --verify cũng kiểm tra nó. Một lần pull xác minh thực hiện cùng ba phép so sánh trên các lock nằm cạnh các Recipes và FeatureRecipes mà Release chạm tới trong các thư mục catalog của bạn, báo cáo mọi pin mà một lần build sẽ từ chối, với cùng mã và cùng lời lẽ, thoát với mã khác 0 nếu có, và không ghi lock nào.
Nơi không có lock nào được so sánh. Một Recipe hoặc FeatureRecipe được phân giải từ registry thay vì từ một trong các thư mục catalog của bạn không có lock nào để build đọc; các nguồn của nó chỉ được đối chiếu với lockfile của Release. Ngoài ra, một nguồn được viết tại một git ref: được ghi trong lock theo commit mà ref đó phân giải tới, trong khi một lần build tìm pin của nguồn theo phiên bản mà thực thể nêu, nên hàng đó không bao giờ được so sánh — dù bởi build hay bởi một lần pull xác minh. Lockfile vẫn pin commit đó, và mọi lần build đều xác minh archive đã lưu cache với nó.
Bản ghi tin cậy plugin
Một số plugin mà workspace gắn vào không bao giờ định hình đầu ra được kết xuất. Một attachment plugins.governance ở vai trò ir-verdict hoặc render-verdict, và mọi attachment plugins.linter, chỉ trả về một phán quyết chấp nhận hoặc từ chối và không gì khác — không byte nào của chúng đi vào một artifact. Vì vậy chúng không thuộc phần mà một bản build tái tạo chính xác từng byte, và lockfile, vốn ghim đúng phần đó, không phải là nơi dành cho chúng.
Thay vào đó, danh tính của chúng được ghi vào một tệp thứ hai được commit: plugins-trust.yaml, nằm cạnh lockfile. Tệp này chứa một mục cho mỗi plugin như vậy, ghi lại tọa độ danh tính của plugin, phiên bản được chọn cho nó và digest nội dung của artifact đã được phân giải — cùng với chữ ký mà pull đã xác minh cho artifact đó, nếu có xác minh, và, khi nhà phát hành đã đánh dấu ngừng hỗ trợ artifact đó kể từ khi phát hành, dấu hiệu mà pull đã tìm thấy và xác minh. Schema của bản ghi tin cậy plugin mô tả từng trường của tệp.
Hãy commit plugins-trust.yaml cùng với lockfile, vì cùng lý do bạn commit lockfile: một bản ghi được giữ ngoài hệ thống quản lý phiên bản là bản ghi không ai có thể xem xét và không gì có thể so sánh với nó. Khi đã được commit, nó là một tuyên bố chung về việc mỗi attachment đó đã được phân giải thành plugin nào, và một diff trên nó chỉ ra danh tính đã thay đổi.
Tệp chỉ xuất hiện khi có điều gì đó cần ghi lại. Một workspace không gắn plugin trả về phán quyết nào thì không phân giải danh tính nào như vậy, nên pull không ghi tệp nào và không nói gì về nó — đó là sự vắng mặt, không phải một tệp bị thiếu. Khi pull tạo tệp, nó nêu tên tệp đã tạo và nhắc bạn commit tệp đó. Một lần pull sau đó sẽ thêm danh tính mà bản ghi chưa có và giữ nguyên chính xác mọi danh tính đã được ghi.
Mọi thay đổi đối với tệp này đều được thông báo, và không có gì khác được thông báo. Một lần pull làm thay đổi bản ghi sẽ in một dòng cho mỗi mục đã thay đổi, nêu tên plugin và loại thay đổi: một danh tính được ghi lần đầu, một danh tính được chấp nhận thay cho danh tính đang giữ (nêu cả hai, để bạn thấy cái gì đã bị hoán đổi), một dấu ngừng hỗ trợ được ghi cho artifact mà một mục đã nêu, một dấu ngừng hỗ trợ được xóa khỏi mục, một chữ ký được ghi vào hoặc xóa khỏi mục, hoặc mục bị loại bỏ. Dòng thông báo tạo tệp ở trên là riêng biệt và nói về tệp chứ không về một mục, nên lần phân giải đầu tiên nói cả hai: tệp này mới và phải được commit, và đây là các danh tính mà nó hiện giữ.
Một lần pull giữ nguyên bản ghi thì không nói gì về nó. Vì vậy một dòng về tệp này có nghĩa là tệp đã commit đã thay đổi và diff của nó đáng đọc — điều này quan trọng ở đây hơn so với lockfile. Mọi thứ lockfile ghim cũng thuộc phần mà một bản build tái tạo chính xác từng byte, nên một thay đổi ở đó có nơi thứ hai để lộ ra; danh tính của một plugin phán quyết thì không có. Tệp này là nơi duy nhất ghi lại việc một cổng kiểm soát bị hoán đổi.
aggrega pull --dry-run không thông báo điều nào trong số này, vì nó không thay đổi gì. Thay vào đó, nó liệt kê bản ghi trong số các tệp mà nó sẽ ghi, như Xem trước những gì một lần pull sẽ ghi mô tả.
Một dấu ngừng hỗ trợ được thêm vào một mục bản ghi đã giữ, và điều đó không giống với việc viết lại mục. Nếu nhà phát hành đánh dấu ngừng hỗ trợ một plugin bạn đã tin cậy, lần aggrega pull tiếp theo sẽ ghi dấu hiệu đó vào mục hiện có của plugin — tọa độ, phiên bản và digest không bị động đến, vì artifact không thay đổi và không có gì mới được chấp nhận. Vì vậy một lần pull thông thường có thể thêm một khối deprecation, và chỉ một lần nâng cấp tường minh mới thay đổi danh tính. Một dấu hiệu chỉ được ghi cho artifact mà mục đã nêu, và không lần pull nào truy theo một dấu hiệu đã ngừng được phát hành: một dấu hiệu đã ghi chỉ mất đi cùng với mục mang nó, nghĩa là hoặc khi mục đó bị loại bỏ, hoặc khi một lần nâng cấp tường minh phân giải lại plugin và không tìm thấy dấu hiệu nào trên các byte mà mục đã ghi.
Chữ ký đã xác minh được ghi vào một mục theo cùng cách, và mỗi lần pull đều trả lời lại từ đầu. Pull xác minh chữ ký của từng plugin này theo chính sách tin cậy của registry trong mỗi lần chạy — một plugin do registry cung cấp được tải theo phiên bản của nó mỗi lần, vì không có gì ghim nó — và ghi những gì đã xác minh vào mục của plugin, cũng không động đến danh tính: chế độ, bên ký đã khớp, và digest của gói chữ ký mà nó đã lưu cache, cùng một signature mà một mục lockfile mang. Khác với dấu hiệu, câu trả lời này thay thế những gì mục đang giữ, và khi pull không xác minh chữ ký nào — plugin không mang chữ ký và không yêu cầu chữ ký, hoặc skip_signature_verification hay một registry advisory đã chấp nhận nó — mục sẽ không ghi chữ ký nào. Gói chữ ký đã xác minh cũng được lưu cache lại, và một bản cache không còn khớp với digest của nó sẽ được ghi lại. Vì vậy một mục bị mất chữ ký, một mục mang chữ ký sao chép từ plugin khác, một mục có gói chữ ký trong cache bị xóa hoặc bị sửa đổi, hoặc một bản ghi bị xóa hay được viết trước khi chữ ký được ghi, đều được sửa bởi lần aggrega pull thông thường tiếp theo. Một bản build buộc mỗi plugin như vậy tuân theo thực tế đó: xem Bản ghi tin cậy plugin trên trang build.
Một danh tính được phân giải không khớp với danh tính đã ghi sẽ làm dừng lần pull. Một mục đã ghi nêu cả phiên bản lẫn digest, nên việc một trong hai thay đổi là cùng một sự kiện: plugin sẽ chạy không phải là plugin mà bản ghi đã được xem xét. Thông báo chẩn đoán nêu tên plugin, những gì bản ghi giữ và những gì lần phân giải này báo cáo, trên cả hai trục cùng lúc — và pull dừng lại mà không động đến bản ghi, nên danh tính đã được xem xét vẫn còn đó để so sánh. Nó dừng khi chỉ riêng phiên bản thay đổi (một lần phát hành lại mà byte không đổi) đúng như khi chỉ riêng digest thay đổi (một lần đẩy lại ở cùng phiên bản).
aggrega pull --verify thực hiện cùng phép so sánh. Nó không ghi tệp nào trong số các tệp mà một lần pull commit, nên nó không chấp nhận gì; nó báo cáo liệu các tệp đó có còn mô tả những gì một lần pull sẽ phân giải hôm nay hay không, và bản ghi là một trong số đó. Nó cũng đối chiếu chữ ký của từng mục với chữ ký mà chính quá trình xác minh plugin của pull đưa ra, và báo cáo một mục có chữ ký mà một lần pull sẽ ghi, thay thế hoặc xóa — cùng một plugin mà bản ghi không có mục nào trong khi một bản build từ chối nó vì không ghi chữ ký — như Nó so sánh các chữ ký đã ghi, trong cả hai tệp mô tả.
Để chấp nhận một danh tính mới, hãy yêu cầu nó theo tên: aggrega pull --upgrade --release <release> <plugin>, nêu tên plugin như attachment trong .aggrega-config.yaml của bạn nêu, không kèm hậu tố phiên bản nào. Lệnh này phân giải lại đúng một plugin đó và viết lại mục của nó, giữ nguyên mọi phụ thuộc đã ghim khác và mọi danh tính đã ghi khác — và nó hoạt động ngay cả khi plugin không có ghim trong lockfile, vì một mục tiêu được nêu tên cũng có thể nêu một trong các attachment đó. Một lệnh aggrega pull --upgrade trơn, vốn phân giải lại mọi phụ thuộc, cũng phân giải lại và viết lại mọi danh tính đã ghi. aggrega build --upgrade cũng vậy, vì nó chạy một lần pull làm mới toàn bộ trơn và không có cách nào nêu tên một mục tiêu đơn lẻ.
Để xóa một danh tính, cũng hãy yêu cầu theo tên. Việc gỡ một plugin khỏi .aggrega-config.yaml không xóa mục của nó, và điều đó là có chủ ý: một lần aggrega pull thông thường không bao giờ xóa mục. Hãy chạy aggrega pull --upgrade --release <release> <plugin>, nêu tên plugin như bản ghi nêu — tọa độ danh tính của nó, chính là chuỗi mà thông báo dừng bên dưới in ra — và mục sẽ bị loại bỏ, giữ nguyên mọi phụ thuộc đã ghim khác và mọi danh tính đã ghi khác. Một lệnh aggrega pull --upgrade trơn loại bỏ mọi mục không còn attachment phán quyết nào nêu tên, trong cùng lượt phân giải lại mọi thứ khác.
Việc xóa mục cuối cùng để lại tệp ở nguyên chỗ và rỗng thay vì xóa tệp. Một bản ghi rỗng không chứa gì, nên nó không ghim gì và không dừng gì — giống như không có bản ghi nào — và việc giữ tệp có nghĩa là thao tác xóa hiện ra trong diff của tệp dưới dạng một thao tác xóa.
Một bản ghi không thỏa mãn schema của nó sẽ dừng mọi lệnh đọc nó — một lần build, một lần lint trong phạm vi release, và một lần pull, kể cả một lần pull không có gì của riêng nó để ghi. Một bản ghi đã được làm rỗng và một bản ghi bị hỏng được cố ý phân biệt: làm rỗng là cách xóa mục cuối cùng, và một bản ghi đã làm rỗng giữ im lặng, còn một tệp có nội dung không còn phân tích cú pháp được là một lỗi chứ không phải một bản ghi rỗng — nếu đọc nó như rỗng thì việc cắt cụt tệp sẽ trở thành một cách để tắt phép so sánh. Hãy khôi phục nó từ hệ thống quản lý phiên bản để lấy lại các danh tính đã được xem xét.
Một plugin được cung cấp từ bản sao bên trong tệp nhị phân của trình biên dịch sẽ không được ghi lại. Pull ghi lại những gì nó thu nhận — tải về từ một registry, hoặc đọc từ cache — và không có gì được thu nhận từ tệp nhị phân: các byte đó được xác định bởi phiên bản trình biên dịch mang chúng, nên không có lần phân giải riêng nào để ghi lại. Vì vậy, việc gắn một plugin mà tệp nhị phân đã mang sẵn không tạo ra mục nào cho nó. Đó là bản ghi chỉ giữ phạm vi các artifact được thu nhận, chứ không phải một lần phân giải bị thất bại.
Một lần build, một lần lint trong phạm vi release và một lần xác thực trong phạm vi release đối chiếu cấu hình workspace với bản ghi. Trước khi bất kỳ attachment nào trong số đó chạy, aggrega build, aggrega lint --release và aggrega validate --release — cùng các thao tác tương tự được gọi qua aggrega serve và aggrega mcp — so sánh các verdict attachment mà cấu hình nêu tên với các mục mà bản ghi chứa. Một plugin có digest của artifact đã phân giải không phải là digest được ghi lại sẽ bị từ chối thay vì được chạy. Một mục trong bản ghi không được attachment verdict nào trong cấu hình giải thích sẽ dừng lần chạy: một cổng kiểm soát đã được xem xét và nay vắng mặt để lại đầu ra không thể phân biệt với đầu ra mà cổng đó đã chấp thuận, và đó chính là điều mà người đọc đầu ra không thể thấy. Thông báo dừng nêu tên plugin và đưa ra hai cách khắc phục khác nhau tùy theo ý định của bạn — gắn lại plugin nếu việc gỡ bỏ là nhầm lẫn, hoặc chạy lệnh nâng cấp tường minh ở trên nếu đó là chủ ý — và nó in sẵn lệnh nâng cấp đó để chạy. Chiều ngược lại — một attachment mà bản ghi chưa chứa — là lần nhìn thấy đầu tiên đã mô tả ở trên, và không phép so sánh nào dừng vì nó; yêu cầu chữ ký là ràng buộc duy nhất mà một attachment không có mục không thoát được. Ba bề mặt đó cũng đối chiếu mỗi plugin chúng đọc từ cache với chữ ký mà mục của nó ghi lại, khi tải plugin, như trang build mô tả cho một lần build. Các phạm vi lint toàn catalog và một thực thể đơn lẻ không tham chiếu bản ghi nào.
Một lần xác thực được đối chiếu với bản ghi vì nó chạy cùng các kiểm tra mà một lần build chạy. aggrega validate --release đi tới mọi kiểm tra mà aggrega build đi tới, chỉ trừ việc ghi các artifact, kể cả các plugin cổng kiểm soát — đó là điều khiến “this validates” có nghĩa giống như “this builds” — nên danh tính của plugin nó chạy được so sánh với bản ghi đúng như của một lần build. Các phạm vi khác của aggrega validate không bị đối chiếu với bản ghi: việc xác thực toàn bộ catalog, một thực thể đơn lẻ, hay một tệp nhị phân plugin hoàn toàn không đọc các plugin attachment của workspace, nên không có verdict plugin nào chạy trong đó và không có gì để bản ghi ràng buộc.
Việc đối chiếu một cấu hình với bản ghi xác lập sự hiện diện và danh tính, và không gì ngoài chúng. Nó xác lập rằng mọi cổng kiểm soát mà bản ghi nêu tên vẫn được gắn, và mỗi cổng chạy từ artifact được ghi lại cho nó. Nó không xác lập rằng một cổng đã chạy có trả về phán quyết hay không, và có một trường hợp như vậy không được phát hiện ở đâu cả: một attachment có function nêu tên một export mà plugin có khai báo, nhưng không phải export phán quyết mà socket của nó đọc, và có đầu ra không mang trường cấp cao nhất nào ngoài hình dạng mà socket đó mong đợi — đối tượng rỗng là ví dụ đơn giản nhất — sẽ chạy, không trả về gì để từ chối, và cho build đi qua. Đầu ra của nó không thể phân biệt với đầu ra của một cổng chấp thuận, và không phép so sánh nào với bản ghi có thể nhận ra, vì không có gì sai trong bản ghi: plugin đã chạy chính là plugin được ghi lại, và nó chỉ đơn giản là không chạy gì. Hai trường hợp lân cận thì có dừng, nên giới hạn này không rộng hơn những gì đã nêu — một function nêu tên một export mà plugin không khai báo sẽ bị từ chối khi plugin được tải, và một đầu ra mang trường cấp cao nhất mà hình dạng của socket không khai báo sẽ bị từ chối thay vì được đọc như một danh sách phán quyết tình cờ rỗng. Vì vậy, chỉ riêng một danh tính được ghi lại không đủ để một cổng kiểm soát đã thực sự đánh giá bất cứ điều gì.
Digest được ghi lại chi phối các plugin mà workspace phân giải từ cache do aggrega pull điền vào, và không chi phối gì mà nó phân giải theo cách khác. Đó là cách phân giải mà một verdict attachment thường đi theo — không có gì ghim nó trong lockfile, nên các byte của nó đến từ cache, và lần đọc đó là nơi digest đã phân giải được so sánh với digest đã ghi lại. Một verdict plugin mà workspace phân giải theo cách khác không bao giờ đi tới lần đọc đó, và được chi phối bởi bất cứ điều gì chi phối cách nó thực sự được phân giải thay vì bởi bản ghi: các byte được cung cấp từ bản sao bên trong tệp nhị phân của trình biên dịch được xác định bởi phiên bản trình biên dịch mang chúng, một tệp .wasm nằm cạnh thực thể catalog của nó là một tệp trong thư mục catalog của chính bạn, một đường dẫn hệ thống tệp tường minh là đường dẫn bạn đã chỉ định, và một plugin có ghim trong lockfile được chi phối bởi ghim đó. Nửa còn lại của việc đối chiếu cấu hình với bản ghi không bị giới hạn như vậy: mọi mục mà bản ghi chứa vẫn phải được một attachment trong cấu hình giải thích, bất kể plugin đó được phân giải thế nào. Vì vậy, bản ghi xác lập rằng các cổng kiểm soát nó nêu tên vẫn được gắn, bất kể cái gì cung cấp chúng, và nó xác lập danh tính artifact của những cổng được cung cấp từ cache.
Tuân theo và cập nhật
Theo mặc định, aggrega pull tuân theo lockfile hiện có: một phụ thuộc đã được ghim sẽ phân giải về đúng phiên bản đã ghim (được xác minh theo digest đã ghim), chỉ những tham chiếu chưa được ghim mới được phân giải và thêm vào, và các ghim cho những tham chiếu mà Release không còn với tới sẽ bị loại bỏ. Vì vậy, pull lại một Release không thay đổi là một thao tác không làm gì — nó tái tạo cùng một lockfile giống hệt từng byte (kể cả generated_at). Thêm một phụ thuộc mới, hoặc pull sau khi một chỉnh sửa thủ công đã xóa một ghim, chỉ phân giải đúng khoảng trống đó và giữ nguyên mọi ghim khác.
Một phụ thuộc mà lần pull lại đọc từ cache được ghi nhận đúng như lần pull đã tải nó ghi nhận. Hàng của nó giữ phiên bản, digest của nội dung và manifest_digest — giá trị sau được lấy từ manifest lưu cạnh nội dung trong cache — cùng với signature và deprecation mà lần pull đó đã xác minh tại registry. Không thông tin nào trong số đó được tra cứu lại khi một bản build vẫn chấp nhận hàng đó, và --detail báo cáo phụ thuộc như vậy là cache-reuse, nên một lần pull lại mà mọi phụ thuộc đều đã có trong cache, trên một lockfile ghi nhận mọi chữ ký mà cấu hình tin cậy yêu cầu và chỉ những chữ ký mà bản build chấp nhận, sẽ ghi ra cùng một lockfile dù có kết nối được tới registry hay không.
Một lần pull lại tra cứu lại chữ ký đúng ở những chỗ mà bản build sẽ từ chối hàng đó, và có hai loại hàng như vậy.
- Một chữ ký bắt buộc mà lockfile không ghi nhận. Khi cấu hình tin cậy yêu cầu chữ ký cho một phụ thuộc do cache cung cấp và hàng trong lockfile không ghi nhận chữ ký nào — hàng đã bị chỉnh sửa, lockfile được ghi mới trên một cache do lần pull trước đã điền, hoặc yêu cầu được thêm vào sau lần pull đã ghi hàng đó — lần pull lại sẽ hỏi registry của phụ thuộc đó về chữ ký của nó, theo digest của manifest lưu cạnh nó trong cache, đúng như cách làm với một phụ thuộc được tải về, và ghi nhận chữ ký đã xác minh vào hàng. Hàng đó chính là hàng mà bản build từ chối (No verified signature is recorded for an artifact that requires one (Không có chữ ký đã xác minh nào được ghi nhận cho một artifact yêu cầu chữ ký)), nên pull lại là cách gỡ bỏ sự từ chối đó. Một registry không đính kèm chữ ký nào, hoặc một chữ ký mà cấu hình tin cậy không chấp nhận, sẽ dừng lần pull lại giống như nó dừng một lần pull đã tải phụ thuộc đó. Các thiết lập cho phép một lần pull chấp nhận phụ thuộc không có chữ ký sẽ giữ nguyên hàng như vậy và không hỏi gì về nó:
skip_signature_verificationở cấp cao nhất, cùng công tắc đó trên mục riêng của registry trừ khi một loại được chính sách ký toàn workspace yêu cầu, và một registry được đánh dấuadvisory. - Một chữ ký đã ghi nhận mà bản build không chấp nhận. Khi hàng ghi nhận một chữ ký có gói chữ ký trong cache đã bị xóa hoặc thay đổi sau lần pull đã lưu nó vào cache — hoặc một
signatuređược sao chép từ hàng khác, có gói còn nguyên nhưng được tạo cho một artifact khác — bản build sẽ từ chối hàng đó bất kể yêu cầu ký nói gì (A cached signature bundle does not match the digest recorded for it (Gói chữ ký trong cache không khớp với digest được ghi nhận cho nó), A recorded signature was made for a different artifact (Chữ ký đã ghi nhận được tạo cho một artifact khác)). Vì vậy, lần pull lại hỏi lại registry của phụ thuộc đó về chữ ký, bất kể yêu cầu nói gì, qua cùng quá trình xác minh mà một phụ thuộc được tải về trải qua: kết quả xác minh thay thế chữ ký của hàng, và gói mà nó chỉ đến được lưu lại vào cache, bản sao trong cache không còn khớp digest sẽ được ghi đè — nhờ đó hàng và cache giữ đúng những gì lần pull đã tải phụ thuộc để lại. Một chữ ký mà cấu hình tin cậy không chấp nhận sẽ dừng lần pull lại giống như nó dừng một lần pull đã tải phụ thuộc đó, và một registry không đính kèm chữ ký nào khi chữ ký là bắt buộc cũng vậy. Khi quá trình xác minh không ghi nhận chữ ký nào —skip_signature_verificationở nơi nó áp dụng, vốn không hỏi gì, một registry không đính kèm chữ ký khi không bắt buộc, hoặc một registryadvisorykhi không có gì được xác minh — chữ ký của hàng bị xóa, điều mà bản build chấp nhận dưới cùng các thiết lập đó.
Một hàng có chữ ký đã ghi nhận mà bản build chấp nhận sẽ không được hỏi lại, và một hàng không ghi nhận chữ ký nào mà không có gì yêu cầu chữ ký cũng vậy.
Một phụ thuộc được nêu tên mà không có registry, trong một workspace hiện không nêu default_registry nào, thì không thể hỏi về nó. Hàng của nó đã được gắn với một registry bởi lần pull ghi nhận chữ ký của nó, và khi không có mặc định thì không có registry nào để hỏi. Khi một hàng như vậy ghi nhận chữ ký mà bản build không chấp nhận, lần pull lại dừng với chính sự từ chối của bản build, cho biết không có registry nào được cấu hình để hỏi lại về hàng đó, và giữ nguyên lockfile. Cấu hình registry mà phụ thuộc đến từ đó làm default_registry rồi pull lại sẽ khắc phục điều này.
Điều mà sự tuân theo đó chi phối là những gì registry hoặc cache cung cấp. Một thực thể do thư mục catalog cục bộ cung cấp được phân giải từ thư mục đó, theo phiên bản mà tệp của nó khai báo, và mục lockfile ghi nhận cho nó không được tham khảo trong quá trình này. Lockfile vẫn ghi nhận thực thể như vậy, nên bạn sẽ thấy nó ở đó — nhưng chỉnh sửa thủ công mục đó không giữ thực thể ở phiên bản bạn đã viết, và lần đối chiếu tiếp theo sẽ ghi lại mục đó cho khớp với tệp. Để thay đổi phiên bản của một thực thể cung cấp cục bộ mà một Release phân giải, hãy sửa tệp catalog thay vì lockfile.
Một ghim chỉ định các byte, không phải một vị trí, nên một mục cache không còn giữ đúng ghim của nó sẽ bị bỏ qua thay vì được tin cậy. Một thực thể được sửa tại chỗ — nội dung mới dưới cùng version — khiến cache nội dung giữ nội dung cũ dưới tên và phiên bản đó. Thư mục catalog được đọc trước, nên một thực thể mà thư mục đó vẫn cung cấp được ghim từ tệp của nó và mục cũ không bao giờ được đọc. Lần render mà pull chạy để phát hiện các đầu vào bên ngoài của Release đọc từng ghim theo cách bản build làm, từ thư mục catalog giữ các byte đã ghim, và báo cáo mục đã bỏ qua bằng thông báo mà aggrega build in ra. Khi không có thư mục catalog nào cung cấp thực thể và có thể kết nối tới registry, pull sẽ tải lại phiên bản đã ghim, ghi lại mục, và thông báo trên standard error, nêu tên mục và cả hai digest:
reuse: cache entry for <name>:<version> held <digest the entry held>, not the pinned <pinned digest>; refreshed from the registry (pin unchanged)Các byte được tải về được đối chiếu với ghim như mọi lần tải dưới một ghim, nên một registry cung cấp byte khác dưới phiên bản đó sẽ dừng pull, như mô tả bên dưới. Khi không có nguồn nào giữ các byte đã ghim — không thư mục catalog nào cung cấp thực thể, mục cache giữ byte khác, và không registry nào cung cấp phiên bản đã ghim hoặc lần chạy không kết nối được registry nào — pull và aggrega pull --verify dừng với E0135 — hoặc E0133 khi manifest của mục cache không phải manifest mà lockfile ghim — nêu từng nguồn đã đọc và nội dung nó giữ; khi lần chạy không kết nối được registry nào, thông báo dừng cũng nêu bước tải lại phiên bản đã ghim.
Để cập nhật các phiên bản đã ghim, hãy chạy aggrega pull --upgrade --release <release> — lệnh này bỏ các ghim hiện có và phân giải lại mọi phụ thuộc về các phiên bản mới nhất thỏa mãn. Cập nhật là một hành động tường minh; mặc định không bao giờ làm trôi một phụ thuộc đã ghim. Điều này giống quy ước của npm ci / cargo / go build (mặc định hiện thực hóa lock; cập nhật là tùy chọn chủ động), và đó là điều làm cho việc pull tự động của aggrega build an toàn — build phân giải đúng những gì lockfile ghim, không bao giờ âm thầm thay đổi phiên bản.
Dạng không đối số đó bỏ mọi ghim đã ghi nhận, nên nó yêu cầu xác nhận trước khi làm gì. Hãy trả lời trước bằng --yes khi dùng không tương tác; khi standard input không phải terminal và không có --yes, lệnh sẽ từ chối thay vì chờ một câu trả lời không ai có thể đưa ra. Nêu tên các mục tiêu (aggrega pull --upgrade --release <release> <uri>) giữ mọi ghim không được nêu tên, nên dạng đó không hỏi gì. aggrega build --upgrade chạy dạng không đối số và được kiểm soát theo cùng điều kiện.
Nếu các byte của một phiên bản đã ghim trong registry không còn khớp với digest mà lockfile đã ghi lại (một vi phạm tính bất biến ở phía upstream), pull sẽ dừng với một lỗi toàn vẹn thay vì âm thầm chấp nhận các byte đã thay đổi — hãy chạy --upgrade để chủ động ghim lại.
Kiểm tra lockfile mà không ghi nó
aggrega pull --verify --release <release> trả lời một câu hỏi: nếu chạy aggrega pull ngay bây giờ thì lockfile, hoặc bản ghi tin cậy plugin bên cạnh nó, có thay đổi không? Lệnh thực hiện quá trình phân giải mà một lần pull sẽ thực hiện, so sánh lockfile và bản ghi với kết quả đó, rồi dừng lại trước khi bất cứ thứ gì một lần pull cam kết được ghi ra — lockfile, bản ghi tin cậy plugin và mọi entity.lock đều được giữ nguyên. Lệnh thoát với mã khác 0 khi thiếu lockfile và khi có bất kỳ khác biệt nào, nêu tên từng khác biệt. Các dấu đánh dấu ngừng hỗ trợ (deprecation) không được so sánh, như phần dưới mô tả. Lệnh bị từ chối khi đi cùng --upgrade, cùng --dry-run, và cùng --pin-sources dù cờ đó được gán giá trị nào: một lần verify không ghi lại pin mà một entity.lock còn thiếu, cũng không dừng vì nó, nên cờ này sẽ không thay đổi gì.
Lệnh tôn trọng các pin đã ghi đúng như một lần pull. Một phụ thuộc mà lockfile pin sẽ được phân giải ở phiên bản đã pin và được kiểm tra theo digest đã pin, và một thực thể do một thư mục catalog cục bộ cung cấp sẽ được phân giải từ thư mục đó, như Tôn trọng và cập nhật mô tả. Vì vậy:
- Một tham chiếu mà registry của nó đã phát hành phiên bản mới hơn kể từ lần pull không phải là sai lệch. Một lần pull sẽ giữ nguyên pin của nó, nên lockfile vẫn là lockfile mà một lần pull sẽ ghi;
aggrega pull --upgradelà cách để tiếp nhận phiên bản mới hơn. - Một registry hiện phục vụ các byte khác dưới một phiên bản đã pin sẽ làm dừng lần verify bằng chính lỗi toàn vẹn làm dừng một lần pull, thay vì báo cáo thay đổi đó là sai lệch.
- Một dòng lockfile bị sửa thủ công, một Release đã bị sửa, và một thực thể bị sửa trong thư mục catalog cục bộ đều được báo cáo, vì mỗi thứ là một khác biệt giữa lockfile và những gì một lần pull phân giải hiện tại.
Lệnh đọc và điền bộ đệm như một lần pull. Một mục mà bộ đệm lưu dưới pin của nó — một thực thể catalog, hoặc tệp .wasm của một plugin — được đọc từ đó mà không hỏi registry, điều này cho phép một lần verify chạy dưới chế độ ngoại tuyến trên một workspace mà một lần pull có kết nối đã điền sẵn. Một mục bộ đệm không có sẽ được tải về, như một lần pull tải nó, và một mục không còn khớp với pin của nó được xử lý đúng như một lần pull xử lý. Vì vậy một lần verify có thể bổ sung vào bộ đệm, nhưng không bao giờ di chuyển một pin.
Lệnh so sánh các chữ ký đã ghi, trong cả hai tệp
Chữ ký mà một lần pull đã xác minh cho một artifact là một phần của những gì nó ghi: signature trên một mục lockfile, và trên một mục của plugins-trust.yaml đối với một plugin được gắn ở vai trò phán quyết. Khi các pin đã khớp, một lần verify đối chiếu mọi chữ ký đã ghi với chữ ký mà một lần pull sẽ ghi hiện tại, và báo cáo từng chữ ký mà một lần pull sẽ ghi ở nơi chưa có, thay thế, hoặc xóa, dưới A recorded signature is not the one a pull would record (Chữ ký đã ghi không phải là chữ ký mà một lần pull sẽ ghi). Mọi mục như vậy, trong cả hai tệp, đều được nêu tên trong cùng một lần chạy.
Việc tra cứu những mục lockfile nào là lựa chọn của chính lần pull. Một lần pull lại hỏi registry về chữ ký của một mục đúng ở những chỗ mà Tôn trọng và cập nhật mô tả, và một lần verify đọc cùng lựa chọn đó:
- Hai loại được báo cáo mà không hỏi registry, vì một lần pull sẽ ghi lại chúng bất kể registry trả lời gì: một mục do bộ đệm phục vụ không ghi chữ ký nào trong khi cấu hình tin cậy yêu cầu có — lần pull sẽ ghi chữ ký của artifact, hoặc dừng lại nếu không xác lập được chữ ký nào — và một mục có chữ ký đã ghi được tạo cho một artifact khác, mà lần pull sẽ thay bằng chữ ký của chính artifact đó.
- Mọi mục khác mà một lần pull sẽ tra cứu lại đều được hỏi, vì chỉ câu trả lời của registry mới cho biết lần pull có thay đổi nó hay không: một mục có các byte do lần verify này tải về, và một mục có gói chữ ký trong bộ đệm đã bị xóa, không đọc được hoặc đã bị sửa đổi. Lần verify hỏi registry, như lần pull sẽ làm, và báo cáo mục đó nếu câu trả lời ghi, thay thế hoặc xóa chữ ký của nó. Gói chữ ký mà nó đã xác minh được lưu vào bộ đệm như một lần pull lưu, nên một mục có gói trong bộ đệm đã bị xóa, trong khi registry vẫn phục vụ chữ ký đã ghi, sẽ vượt qua và để lại bộ đệm đã được sửa chữa.
Một mục có chữ ký đã ghi mà bản build chấp nhận, và một mục không ghi chữ ký nào mà không có gì yêu cầu chữ ký, đều không được hỏi, bởi một lần pull cũng như một lần verify.
Bản ghi tin cậy plugin được đối chiếu với cùng lần pull đó. Mỗi lần pull đều xác minh chữ ký của từng plugin được gắn ở vai trò phán quyết tại registry của nó, và một lần verify cũng vậy, báo cáo một mục có chữ ký mà việc xác minh đó sẽ ghi, thay thế hoặc xóa. Một plugin mà bản ghi không có mục nào được báo cáo nếu bản build từ chối nó vì không ghi chữ ký, vì một lần pull sẽ ghi một mục mang chữ ký của nó và bản build từ chối plugin cho đến lúc đó. Mọi trường hợp khác là lần nhìn thấy đầu tiên, mà một lần verify không báo cáo, cũng như nó không báo cáo bất kỳ danh tính nào mà bản ghi chưa có. Dưới chế độ ngoại tuyến, một lần verify không hỏi registry nào về các plugin này, và Ngoại tuyến mô tả những gì nó báo cáo thay vào đó.
Các dấu đánh dấu ngừng hỗ trợ không được so sánh. Một dấu được gắn vào artifact sau lần pull là trạng thái của registry, và nó thay đổi mà không có gì trong workspace thay đổi; một lần verify thất bại vì nó sẽ làm hỏng một lần kiểm tra trên các tệp bạn không hề động đến. Cũng vì lý do đó, một dấu đã ghi chỉ đưa ra khuyến cáo cho bản build chứ không làm nó dừng lại. Vì vậy một lần pull có thể ghi một dấu trên một mục mà lần verify đã cho qua.
Xem trước những gì một lần pull sẽ ghi
aggrega pull --dry-run --release <release> phân giải các phụ thuộc đúng như một lần pull thông thường, rồi thay vì ghi, nó in ra những gì lẽ ra nó đã ghi: một dòng tiêu đề nêu đường dẫn của từng tệp, theo sau là nội dung mà tệp đó sẽ chứa.
aggrega pull --dry-run --release release.yamlNó nêu tên mọi tệp, không chỉ lockfile. Lockfile, tệp entity.lock bên cạnh mỗi Recipe và FeatureRecipe có các pin đã ghi sẽ thay đổi dưới --pin-sources, và bản ghi tin cậy plugin đều xuất hiện trong cùng một báo cáo, vì một bản xem trước chỉ hiển thị lockfile sẽ khiến bạn hiểu rằng lockfile là thứ duy nhất thay đổi. Một lần pull sẽ dừng trên một thực thể chưa được pin thì cũng dừng dưới --dry-run, vì cùng lý do: những gì bản xem trước hiển thị chính là những gì lần pull sẽ làm. Các tệp mà một lần pull sẽ giữ nguyên từng byte hoàn toàn không xuất hiện — một tên trong báo cáo nghĩa là tệp đó sắp thay đổi. Dòng cuối cùng đếm số tệp này, và một workspace mà lần pull sẽ không thay đổi báo cáo số lượng bằng không.
Không có gì trên đĩa thay đổi. Không lockfile nào được ghi hay tạo, không entity lock nào được ghi hay xóa, và không bản ghi tin cậy nào được tạo hay sửa đổi. Khi một capability được nhiều hơn một provider plugin phục vụ và chưa có gì chọn giữa chúng, lần chạy sẽ dừng và nêu những gì cần cung cấp thay vì đề nghị ghi lựa chọn vào cấu hình của bạn — một bản xem trước không chỉnh sửa tệp cấu hình khi đi qua.
Bản thân quá trình phân giải vẫn chạy, nên cache vẫn được lấp đầy. Những đầu vào bên ngoài mà một Release sử dụng là kết quả của việc render nó, và một lần chạy từ chối phân giải sẽ không có gì để báo cáo, nên --dry-run tải về và lưu trữ đúng như một lần pull. Nội dung trong .aggrega/cache chỉ được đọc thông qua các pin mà lockfile ghi lại, nên việc lấp đầy nó không thay đổi gì mà một lần build phân giải; những gì một lần dry run hiển thị là những gì một lần pull sẽ ghi.
Một --upgrade đơn thuần không hỏi gì dưới cờ này. Việc xác nhận tồn tại vì một lần làm mới toàn bộ sẽ bỏ mọi pin đã ghi, còn một bản xem trước không bỏ pin nào — vì vậy aggrega pull --dry-run --upgrade --release <release> là dạng nên dùng khi điều bạn muốn biết là một lần làm mới sẽ khiến bạn mất gì, và nó chạy mà không cần câu trả lời.
Nó không được chấp nhận cùng với --verify, vốn đã không ghi tệp nào trong số đó. Cặp này sẽ khiến cờ không làm gì trong khi trông như thể nó đã làm điều gì đó, nên nó bị từ chối thay vì bị bỏ qua.
Có một điều mà bản xem trước có pin không phải lúc nào cũng hiển thị đầy đủ, và nó sẽ nói rõ khi điều đó xảy ra. Một lần pull được yêu cầu pin sẽ ghi lại tệp entity.lock bên cạnh mỗi Recipe và FeatureRecipe rồi render Release để tìm ra các đầu vào bên ngoài của nó; bản xem trước giữ nguyên các lock đó, nên khi một pin được ghi ở đó đã lỗi thời — chẳng hạn bạn đã sửa một tệp được import kể từ khi nó được pin — lần render đó bị ràng buộc với digest lỗi thời mà lock chưa được ghi vẫn còn lưu, và dừng lại. Mọi thứ khác trong báo cáo đúng là những gì một lần pull sẽ ghi; chỉ các pin đầu vào bên ngoài của lockfile được báo cáo là bị thiếu. Lần chạy nói rõ điều này trên cả đầu ra lẫn diagnostics của nó thay vì đưa cho bạn một lockfile trông như hoàn chỉnh. Lần phân giải đầu tiên của một workspace không bị ảnh hưởng, vì chưa có digest nào được ghi để bất cứ thứ gì bị lỗi thời so với nó.
Thành phần mà các pin này mô tả
Một lockfile ghim những gì một lần build của Release này sẽ sử dụng, vì vậy quá trình phân giải dựng nên đúng thành phần mà lần build đó dựng: nó phân giải các tài liệu, áp dụng các phép biến đổi mà các attachment của workspace khai báo, và đưa kết quả qua các bước kiểm tra mà một lần build thực hiện trên một đồ thị hoàn chỉnh. Từ đó có hai hệ quả, và cả hai đều xuất hiện ở lượt ghi lockfile chứ không phải ở lần build đầu tiên đọc nó.
Một thành phần bị các bước kiểm tra đó từ chối sẽ dừng lệnh pull. Một cạnh uses: có đích không thỏa mãn selector: của socket, một Feature được gắn vào một component mà appliesTo: của nó không chấp nhận, và mọi vi phạm khác mà các bước kiểm tra đó báo cáo đều dừng lệnh này, với cùng chẩn đoán mà một lần build trên cùng các tài liệu in ra — và việc dừng nêu mọi phát hiện trong một lần chạy chứ không chỉ phát hiện đầu tiên, nên một lượt chạy trao cho bạn toàn bộ danh sách cần sửa. Việc này xảy ra trước khi ghi, nên <release-stem>.lock và plugins-trust.yaml được giữ nguyên như cũ, và một Release không build được sẽ không bao giờ được ghi nhận là đã phân giải thành công. Điều này không bao gồm các attachment trả về một phán quyết: không có attachment ir-verdict hay render-verdict nào chạy ở đây, nên một phán quyết từ chối sẽ dừng lần build, lint phạm vi release hoặc kiểm tra hợp lệ phạm vi release đã gọi nó, chứ không phải lệnh này.
Một attachment ở vai trò định hình đồ thị sẽ chạy trong lượt đó, nên một plugin không phân giải được sẽ dừng lệnh pull. Một attachment label-transform quyết định nhãn của node trước khi bất cứ thứ gì được so khớp với chúng, và một attachment annotation-transform chèn các annotation mở rộng thành các attachment Feature — cả hai đều thay đổi nội dung của đồ thị, nên dựng đồ thị nghĩa là phải gọi chúng, và gọi chúng nghĩa là phải có bytes của chính từng plugin. Một plugin mà lượt này không lấy được bytes sẽ dừng lần chạy, nêu tên plugin và những gì không tìm được cho nó — cũng là sự từ chối mà một lần build trên cùng workspace đưa ra khi không lấy được chúng. Những gì nó gọi là danh sách attachment mà lượt này vừa phân giải, mang theo các thiết lập và tệp định nghĩa mà lockfile ghi lại để một lần build sau tái dựng, nên cả hai lượt đều chạy cùng attachment trên cùng đầu vào.
Một Plugin mà một bước pipeline nêu tên nhưng không nơi nào chứa cũng dừng lệnh pull. Mỗi Plugin mà pipeline của một Recipe hoặc FeatureRecipe nêu tên được phân giải cùng các phụ thuộc khác của Release — từ một thư mục catalog, bản sao bên trong binary của trình biên dịch, bộ nhớ đệm nội dung, hoặc registry — và một Plugin không nơi nào trong số đó chứa cũng là Plugin mà một lần build không thể tải được. Vì vậy lệnh pull dừng trước khi ghi bất cứ thứ gì, nêu tên Plugin và Recipe hoặc FeatureRecipe có pipeline nêu tên nó, với điều kiện mà một lần build đưa ra khi đến bước đó (A plugin reference is not a Plugin entity (Một tham chiếu plugin không phải là thực thể Plugin)). Điều đó áp dụng cho mọi Recipe và FeatureRecipe mà Manifest ràng buộc, kể cả cái không được gắn vào đâu trong Release này, vì mỗi cái đều được phân giải và ghim dù nó có được render hay không. Hãy publish Plugin, hoặc đặt nó vào một thư mục catalog cùng tệp .wasm đã build bên cạnh, rồi pull lại.
Việc dừng đó và một lần chạy suy giảm là hai kết quả khác nhau, một cách có chủ ý. Một lần render không thể hoàn tất — trường hợp mà cả Cách quá trình phân giải tìm các đầu vào bên ngoài và Ngoại tuyến đều mô tả — vẫn giữ mọi pin phụ thuộc đúng, nên các pin được ghi và phần thiếu hụt được báo cáo. Một thành phần bị các bước kiểm tra từ chối không phải là thiếu hụt trong những gì đã được phân giải: đó là một Release không build được, nên không có gì được ghim cho nó và lần chạy dừng lại.
Bộ nhớ đệm
Nội dung được kéo về được lưu dưới .aggrega/cache, chia thành một cây con entities/ cho các thực thể catalog, một cây con source-artifacts/ cho các artifact nguồn, và một cây con inputs/ cho các đầu vào bên ngoài mà một lần render sử dụng. Ô của một thực thể catalog được đặt tên theo loại, tọa độ và phiên bản của nó — nên một Component và một Recipe có chung tọa độ và phiên bản vẫn giữ hai ô —, ô của một artifact nguồn theo nơi nó được tải về, phiên bản của nó và một tiền tố của digest nội dung, còn ô của một đầu vào bên ngoài theo digest nội dung của nó; những gì một bản build đọc từ bất kỳ ô nào trong số đó đều được đối chiếu với những gì lockfile ghi lại. Do đó, các ghim phiên bản giống nhau dùng chung một ô giữa các Releases. Mỗi ô artifact nguồn chứa bản lưu trữ có thẩm quyền, một bản giải nén được tạo lại và một tệp metadata nhỏ; bản giải nén được tạo lại ở mỗi lần đọc, vì vậy đầu ra của bản build phụ thuộc vào bản lưu trữ và lockfile, không phụ thuộc vào trạng thái của các tệp đã giải nén.
Mọi tên mà bộ nhớ đệm suy ra từ một giá trị đều là tên mà Windows, Linux và macOS đều chấp nhận. Một tọa độ, một phiên bản, một host registry hoặc một digest chứa những ký tự mà tên tệp không thể chứa: dấu / giữa các phần của tọa độ, dấu : trước phiên bản, bên trong sha256: và trước cổng của registry. Vì vậy mỗi giá trị — một loại, một tọa độ, một phiên bản, một host registry hoặc một digest — được mã hóa trước khi trở thành tên thư mục hoặc tên tệp — chữ thường, chữ số, ., _ và - được viết nguyên như vậy, còn mọi ký tự khác được viết thành một chuỗi thoát bắt đầu bằng +. Component core/devtool/adminer:1.0.0 ở phiên bản 1.0.0 là ô entities/+zx000043omponent/core+zsdevtool+zsadminer+zx00003a1.0.0/1.0.0/, và một ô được đặt tên theo digest nội dung là sha256+zx00003a<hex>. Chữ hoa cũng được thoát, nên hai tọa độ chỉ khác nhau về chữ hoa/thường vẫn giữ hai ô trên hệ thống tệp không phân biệt chữ hoa/thường; một tên mà Windows dành riêng cho thiết bị, chẳng hạn con, được thoát chữ cái đầu tiên; và không tên nào kết thúc bằng dấu chấm. Hai giá trị khác nhau không bao giờ dùng chung một tên, và một giá trị có cùng một tên trên mọi máy. aggrega cache status liệt kê mỗi mục theo các giá trị mà tên của nó được mã hóa từ đó — một thực thể catalog theo tọa độ, phiên bản và loại của nó — chứ không theo các tên đã mã hóa.
Một mục của bản lưu trữ giữ nguyên tên mà nhà phát hành đặt cho nó, nên trên Windows, một mục mà Windows không thể chứa sẽ bị từ chối. Các tệp mà một artifact nguồn hoặc bản lưu trữ của một thực thể catalog mang theo được bố trí dưới các tên mà bản lưu trữ đặt cho chúng, không được bộ nhớ đệm mã hóa. Khi việc giải nén chạy trên Windows, một mục chứa một phần mà Windows không thể chứa như được viết — một tên mà nó dành riêng cho thiết bị, chẳng hạn NUL hoặc aux, ở bất kỳ kiểu chữ hoa/thường nào và có hoặc không có phần mở rộng, hoặc một phần kết thúc bằng dấu chấm hoặc khoảng trắng — bị từ chối với E0340, nêu tên mục đó, và không có gì của bản lưu trữ đó được bố trí. Trên Linux và macOS, một mục như vậy được bố trí đúng như tên của nó. Một mục leo ra khỏi thư mục giải nén bị từ chối trên mọi máy.
Ô của một thực thể catalog chỉ là một mục khi có manifest của nó. Ô chứa nội dung mà một registry đã phục vụ và, bên cạnh đó, manifest mô tả nội dung đó. Một ô chỉ chứa nội dung — một lần tải dừng giữa hai lần ghi, hoặc một tệp được đặt vào đó bằng tay — không phải là một mục: một lần pull, và một lần pull xác minh, sẽ yêu cầu lại registry của thực thể khi có thể kết nối tới một registry, trong khi một bản build, vốn không bao giờ tải về, coi thực thể là bị thiếu, giống như một lần pull khi không thể kết nối tới registry nào.
Những gì vào bộ nhớ đệm phải tuân theo hai điều: hình dạng mà schema của chính thực thể mô tả, và vị trí mà bộ nhớ đệm đặt tên cho nó. Một nội dung được tải từ registry được kiểm tra qua schema của loại của nó — cùng phép kiểm tra dùng khi đọc lại — trước khi được lưu đệm, vì vậy một thực thể hoặc thư viện đã phát hành mà registry phục vụ nhưng schema của chính nó từ chối sẽ dừng lần pull, nêu tên thứ đã được tải, thay vì được lưu đệm rồi gặp lỗi về sau. Và một giá trị dùng để xây dựng vị trí bộ nhớ đệm mà sẽ đặt một tệp đệm ở nơi khác với nơi giá trị đó chỉ định — một phiên bản là một đường dẫn chứ không phải phiên bản, một đường dẫn url nguồn hoặc module_subdir leo lên trên vị trí của nó — bị từ chối tại chỗ vị trí được xây dựng, nêu tên giá trị vi phạm. Một giá trị được viết trong một Recipe hoặc một FeatureRecipe do bạn soạn cũng được kiểm tra như vậy vào thời điểm vị trí bộ nhớ đệm được xây dựng từ nó — và module_subdir của một nguồn git thì sớm hơn, trước khi repository được tải về, như bên dưới.
Một git repository được lưu trữ từ bản checkout của chính nó. Với một nguồn git-repository, lần pull checkout repository tại commit mà nó ghim và lưu trữ thư mục mà module_subdir chỉ định, hoặc toàn bộ repository. Một module_subdir leo lên trên repository như được viết — ../shared, hoặc ..\shared — bị từ chối trước khi repository được tải về, với E0307 trích dẫn giá trị đó, nên không có gì bên cạnh bản checkout được đọc. Một liên kết tượng trưng mà repository commit được lưu trữ như tệp hoặc thư mục mà nó trỏ tới khi đích đó nằm trong repository — bản thân module_subdir có thể là một liên kết như vậy. Một liên kết dẫn ra ngoài repository sẽ dừng lần pull với E0321, nêu tên liên kết và nơi nó dẫn tới, và không có gì được lưu đệm, vì vậy một repository mà bạn pull không thể khiến lần pull sao chép một tệp trên máy của bạn vào artifact. Bản checkout bị xóa khi lần pull dừng, nên thông báo nêu tên liên kết theo vị trí của nó trong repository, cùng repository và revision mà nguồn chỉ định, thay vì một thư mục không còn tồn tại. Việc thay đổi liên kết thuộc về repository. Ranh giới workspace nêu quy tắc mà điều này áp dụng.
Bộ nhớ đệm được neo vào workspace chứ không phải vào thư mục nơi bạn chạy lệnh, vì vậy một workspace có một bộ nhớ đệm và một lần pull chạy từ thư mục con sẽ điền vào cùng kho mà một bản build chạy từ thư mục gốc đọc.
Một lần pull không tìm thấy workspace nào và không có workspace nào được chỉ định sẽ bị từ chối trước khi tải bất cứ thứ gì. Khi không có gì chỉ định thư mục gốc và việc dò tìm không neo được gì — từ thư mục nơi bạn chạy lệnh, hoặc, với một Release được chỉ định bằng đường dẫn tuyệt đối, từ thư mục của chính Release đó — thư mục đó sẽ trở thành thư mục gốc, và một bộ nhớ đệm được ghi bên dưới sẽ biến nó thành một workspace. Vì vậy lần pull dừng lại, không ghi lockfile và bộ nhớ đệm nào, và nêu tên thư mục cùng hai cách giải quyết: chỉ định workspace của bạn bằng --workspace-root hoặc AGGREGA_WORKSPACE_ROOT, hoặc cung cấp cho thư mục đó một .aggrega-config.yaml chứa khối workspace:. Công cụ pull của aggrega mcp, khi được gọi không có workspace_root trên một server khởi chạy không có thư mục gốc, cũng bị từ chối theo cách tương tự; Cấu hình liệt kê các lệnh khác mà điều này áp dụng.
Build ở nơi không thể kết nối mạng
Vì lệnh này là bước duy nhất kết nối ra bên ngoài, một lần chạy có kết nối là đủ để mọi lần build sau đó đều cục bộ. Lần chạy đó ghi lockfile và lấp đầy cache của workspace bằng các byte mà những pin đó chỉ định, và sau đó một lần build không cần gì ngoài chúng.
Ba thứ được mang sang máy không có kết nối:
- Release và lockfile của nó. Commit
<release-stem>.lockbên cạnh Release; đó là thứ cho lần build biết mỗi dependency đã được phân giải thành phiên bản và digest nào. plugins-trust.yaml, khi workspace gắn một plugin trả về verdict. Một lần build đối chiếu các verdict attachment mà cấu hình của nó chỉ định với bản ghi đó trước khi bất kỳ attachment nào chạy, nên việc mang theo bản ghi là điều giữ cho lần build không có kết nối gắn với các danh tính đã được xem xét và với các chữ ký mà pull đã xác minh cho chúng. Commit nó bên cạnh lockfile, như Bản ghi tin cậy plugin mô tả.- Thư mục cache. Các entity, các source artifact và các input đã pin đều nằm trong đó, và mọi thứ mà một thư mục
catalog_dirscục bộ không cung cấp đều được đọc từ đó.
Build trên máy không có kết nối như bình thường. Việc đặt chế độ offline ở đó vẫn đáng làm, dù một lần build trên lockfile đầy đủ đọc closure của nó từ cache: nó biến một lần truy cập mạng tiềm tàng thành một lần từ chối ngay lập tức có nêu tên chế độ, thay vì một lần thử kết nối phải chờ hết thời gian trước. Bất kỳ thứ gì cache không chứa, và bất kỳ external input nào lockfile không pin, đều làm dừng lần build, nêu tên thứ bị thiếu và lần phân giải sẽ pin nó — không có gì được tải ngầm để lấp chỗ trống.
Một máy airgapped và một workspace offline là hai khẳng định khác nhau, và sự khác biệt đó đáng được giữ. Một máy nằm sau air gap có thể chứa một bản sao cục bộ của registry, hoặc một catalog catalog_dirs mang mọi thứ nó cần, khi đó một lần pull thông thường trên máy đó có thể được đáp ứng mà hoàn toàn không cần kết nối ra ngoài. Chế độ offline mô tả những gì một lệnh được phép truy cập, chứ không phải những gì máy đang chứa; Offline trình bày những gì nó từ chối và những gì nó để nguyên.
Ngoại tuyến
Dưới chế độ ngoại tuyến — khóa cấp cao nhất offline trong tệp cấu hình, AGGREGA_OFFLINE trong môi trường, hoặc --offline trên dòng lệnh — aggrega pull từ chối truy cập mạng. Việc từ chối diễn ra trước khi bất kỳ kết nối nào được thử, chứ không phải dưới dạng hết thời gian chờ giữa chừng một lần tải, nên một lần pull ngoại tuyến không chạm tới registry nào và nguồn từ xa nào. Khi một tệp đã commit hoặc một biến đã export thiết lập chế độ này và bạn muốn vượt qua nó cho một lệnh, --offline=false cho phép mạng chỉ riêng cho lần chạy đó.
--upgrade bị từ chối hoàn toàn dưới chế độ này, và đây là tùy chọn duy nhất ở đây bị như vậy. Một lần làm mới toàn bộ đẩy mọi phụ thuộc lên phiên bản cao nhất mà registry hiện cung cấp, nên nó cần hỏi registry hiện đang phục vụ gì. Một lần pull thông thường thì không: nó tôn trọng các pin đã ghi, chỉ phân giải những gì chưa có pin, và do đó có thể được đáp ứng từ những gì máy đang có. Thông báo từ chối cho biết nơi nào trong ba nơi đã thiết lập chế độ này và cách cho phép mạng cho một lần chạy.
Khi đó việc phân giải chỉ dựa vào những gì máy đã có: ngăn xếp tìm kiếm catalog_dirs và bộ nhớ đệm dưới .aggrega/cache. Với một catalog và bộ nhớ đệm đáp ứng mọi tham chiếu, một lần pull ngoại tuyến hoàn tất bình thường và ghi một lockfile thông thường. Lockfile ghi URI, phiên bản đã phân giải và digest của từng phụ thuộc, và không bao giờ ghi nơi nào đã cung cấp các byte — nên một lần pull ngoại tuyến và một lần pull trực tuyến phân giải ra cùng các phiên bản sẽ ghi cùng một lockfile.
Một phụ thuộc mà lần pull ngoại tuyến không thể đáp ứng cục bộ sẽ dừng lần pull đó. Mục đó không bao giờ bị bỏ qua:
- Một thực thể catalog không phân giải được ở đâu sẽ dừng lần pull, nêu tên tham chiếu và nơi nó được tham chiếu, nên cả phụ thuộc bị thiếu lẫn thứ đã yêu cầu nó đều được nêu tên.
- Một
source:từ xa sẽ dừng lần pull, nêu tên nguồn và yêu cầu bạn hoặc cho phép truy cập mạng, hoặc nạp bộ nhớ đệm từ một môi trường có kết nối. - Một phụ thuộc có trong bộ nhớ đệm mà chữ ký bắt buộc của nó không được lockfile ghi lại, hoặc chữ ký đã ghi của nó không được build chấp nhận, sẽ dừng lần pull bằng thông báo từ chối ngoại tuyến, nêu tên phụ thuộc đó: ghi chữ ký nghĩa là phải hỏi registry của nó, như Tôn trọng và cập nhật mô tả. Cho phép mạng cho riêng lần chạy đó sẽ ghi được chữ ký. Một chữ ký đã ghi mà build chấp nhận sẽ không được tra lại, nên nó không làm dừng lần pull ngoại tuyến.
Đầu vào bên ngoài là thứ duy nhất không làm dừng, và thay vào đó nó thông báo điều này. Lần render tìm ra chúng không thể tải những gì chưa được lưu sẵn, nên một lần pull ngoại tuyến trên một Release có đầu vào bên ngoài chưa được pin vẫn hoàn tất, ghi mọi pin phụ thuộc mà nó đã phân giải, và báo cáo ba điều: rằng lần render chưa hoàn tất, những gì nó đã pin, và rằng một lần build Release này sẽ dừng và nêu tên URL đó. Các pin phụ thuộc mà nó ghi là đúng — không gì trong chúng phụ thuộc vào lần render — nên chúng được giữ lại thay vì bị bỏ đi để người đọc phải tạo lại.
Đó là chủ ý chứ không phải một thiếu sót, và không có công tắc nào cho việc này. Một lần pull bỏ đi kết quả đúng sẽ khiến bạn mất phần đã thành công; một lần pull im lặng sẽ đưa cho bạn một lockfile trông như hoàn chỉnh nhưng không phải vậy. Thông báo rõ là kết quả duy nhất cho phép bạn hành động: chạy lại lần pull từ một môi trường có kết nối, hoặc từ một môi trường có bộ nhớ đệm đã chứa nội dung đó, và cùng lệnh ấy sẽ pin nó.
Vì vậy, một lần pull ngoại tuyến là sự từ chối chạm vào mạng chứ không phải một kết quả rút gọn cho mọi thứ mà tài liệu nêu tên, và với đầu vào bên ngoài, đó là một lần phân giải đã hoàn tất cho bạn biết những gì nó không thể với tới. Một lockfile tồn tại là lockfile có phần phân giải phụ thuộc đã hoàn tất; còn các đầu vào bên ngoài của nó có đầy đủ hay không là điều mà chính đầu ra của lần pull cho bạn biết, và là điều mà build sau đó buộc nó tuân theo.
--verify dưới chế độ ngoại tuyến kiểm tra ít hơn, và báo cáo rằng nó như vậy. Hỏi xem một source ref đã ghi hiện trỏ tới đâu nghĩa là phải với tới remote của nó, điều mà chế độ ngoại tuyến từ chối. Vì vậy, --verify ngoại tuyến kiểm tra các phụ thuộc đã pin và bỏ qua khía cạnh đó, và in ra một dòng nói như vậy thay vì báo cáo một sự khớp mà nó chưa từng xác lập. Một chữ ký đã ghi mà chỉ registry của nó mới xác nhận được — trên một mục lockfile có gói chữ ký trong bộ nhớ đệm đã bị xóa hoặc bị sửa — cũng bị bỏ qua theo cách đó, trên một dòng nêu tên từng mục như vậy:
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 itMột chữ ký đã ghi mà lần pull sẽ ghi lại bất kể registry trả lời gì vẫn được báo cáo khi ngoại tuyến, vì không cần câu trả lời nào để biết điều đó, như Nó so sánh các chữ ký đã ghi, trong cả hai tệp mô tả.
Một plugin được gắn ở vai trò phán quyết do registry phục vụ là điểm mà verify ngoại tuyến và pull ngoại tuyến tách biệt. Plugin như vậy không bao giờ được pin trong lockfile, nên mọi lần pull đều phân giải .wasm của nó từ registry, và một lần pull ngoại tuyến trên một workspace gắn plugin đó sẽ dừng tại đó, nêu tên plugin là plugin mà nó không thể phân giải .wasm — ngay cả khi bộ nhớ đệm nội dung có chứa nó, và bất kể registry đó có được đánh dấu advisory hay bỏ qua việc xác minh chữ ký hay không. Ngược lại, verify ngoại tuyến không hỏi registry gì về plugin: nó đọc plugin từ bộ nhớ đệm nội dung, như build đọc, và dừng khi bộ nhớ đệm không chứa .wasm của nó hoặc chứa một tệp không còn khớp với digest mà manifest đã công bố của nó nêu. Nó vẫn đối chiếu danh tính của plugin với bản ghi tin cậy plugin và kiểm tra lại các host function của nó với .wasm đó, và dừng khi một trong hai không khớp, đúng như verify có kết nối. Nó báo cáo plugin khi lần pull ghi lại mục của nó bất kể registry trả lời gì, cũng là khi build từ chối plugin vì mục của nó: vì không ghi chữ ký nào, do mục của nó không ghi chữ ký hoặc bản ghi không có mục nào cho nó, hoặc vì chữ ký mà mục của nó ghi được tạo cho một artifact khác, thứ mà lần pull sẽ thay bằng chữ ký của chính plugin. Mọi mục khác — mục có chữ ký mà build chấp nhận, và mục có gói chữ ký trong bộ nhớ đệm đã bị xóa hoặc bị sửa — nó nêu tên trên một dòng nói rằng chữ ký chưa được kiểm tra, và không báo cáo gì về chữ ký đó:
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 itVì vậy, verify ngoại tuyến bỏ qua một mục có chữ ký mà lần pull có kết nối sẽ thay thế hoặc xóa — chẳng hạn một mục có người ký bị sửa bằng tay, hoặc một mục mà registry không còn gắn — và dòng đó là thứ duy nhất cho biết điều này. Verify trong môi trường air-gap vẫn dùng được; điều nó không cho bạn biết là một ref đã di chuyển kể từ đó hay chưa, hoặc một chữ ký bị bỏ qua có được ghi lại nữa hay không. Một lần kiểm tra chỉ đọc mã thoát chỉ bao quát được những điều đó khi verify chạy có kết nối.
Tích hợp với aggrega build
- Xác minh.
aggrega buildxác minh mọi dependency đã được phân giải với lockfile và dừng lại khi có sai lệch (drift): một entity, một thư viện hoặc một plugin có nội dung không còn khớp với pin của nó, một tham chiếu mà Release giờ đây chạm tới nhưng lockfile không pin, hoặc một tham chiếu được pin mà Release không còn chạm tới, và một tệp Release đã bị chỉnh sửa kể từ lần pull. Hãy chạyaggrega pull --release <release>, lệnh mà thông báo dừng in ra, để xử lý: lần pull phân giải Release theo trạng thái hiện tại, ghi lại các pin đã thay đổi và giữ nguyên mọi pin khác, nên không có gì trôi theo phiên bản mới mà bạn không thay đổi. Khi thứ đã thay đổi là một tệp nằm dưới nguồn cục bộ của một Recipe, lần pull trước tiên chỉ raaggrega pincho entity đó, như Khóa thực thể mô tả. Một lockfile vừa được lệnh này ghi sẽ vượt qua phép kiểm tra đó, vì lệnh chạy cùng phép kiểm tra trước khi ghi; một bản build dừng lại vì sai lệch ngay sau một lần pull là đã được cung cấp đầu vào khác với lần pull — một thư mục--catalogđược truyền cho lệnh này mà không cho lệnh kia, hoặc cấu hình workspace bị chỉnh sửa giữa hai lần chạy — vì vậy hãy chạy cả hai trên cùng các đầu vào.aggrega validate --releasevà mọi lựa chọn củaaggrega inspectcó phân giải một Release đều áp cùng phép kiểm tra đó lên lockfile và từ chối bằng cùng điểm dừng, nên không lệnh nào bỏ qua một lockfile mà bản build từ chối. - Tự động pull. Nếu thiếu lockfile và
auto_pulllà true,aggrega buildsẽ tự động chạy pull trước. Nếuauto_pulllà false, giá trị mặc định của nó, bản build dừng lại và yêu cầu bạn pull. Lần pull mà một bản build chạy tuân theopin_sources_at_pull, nên với một entity chưa được pin, nó dừng lại đúng như một lần pull. Bước pull mà một bản build chạy chính là bước mà trang này mô tả, nên một bản build điền vào một lockfile hiện có sẽ dừng lại khi một source ref bị dịch chuyển, đúng nhưaggrega pull— xem Tính tất định và tính toàn vẹn. - Ngoại tuyến. Ở chế độ ngoại tuyến,
aggrega buildchỉ dùng những gì máy đã có, và từ chối truy cập mạng trước khi thử bất kỳ kết nối nào. Một tham chiếu có nội dung không nằm trong cache sẽ làm bản build dừng lại thay vì thất bại giữa chừng khi tải, và một bản build không có lockfile mà không được yêu cầu điền lockfile sẽ dừng lại và chỉ ra lần pull sẽ điền nó, đúng như khi trực tuyến.--auto-pullkhông bị từ chối: việc điền mà nó yêu cầu chính là lần pull mà trang này mô tả, nên với các catalog entity đã được cache hoặc có trong một catalog cục bộ, nó ghi lockfile mà không cần chạm tới registry — một Recipe có chart được tải từ một nguồn từ xa sẽ được phân giải lại, nên khi ngoại tuyến nó dừng lại ngay cả khi cache có chart đó — và một tham chiếu mà cả hai đều không có — hoặc một tham chiếu đã được cache mà lockfile không ghi lại chữ ký bắt buộc của nó, hoặc có chữ ký đã ghi mà bản build không chấp nhận — sẽ làm nó dừng lại với chính thông báo từ chối của lần pull, chỉ ra tham chiếu đó.--upgradebị từ chối, vì lý do mà Ngoại tuyến nêu. - Tìm kiếm catalog. Pull tuân theo
catalog_dirstừ.aggrega-config.yamlngay cả khi không có--catalognào được truyền — và các thư mục riêng của một Release khi cấu hình cung cấp chúng dướiworkspace.releases— và phân giải cùng một ngăn xếp tìm kiếm ưu tiên kết quả đầu tiên nhưaggrega build, nên các dependency mà nó pin khớp với những gì build tìm kiếm. Một thư mục được liệt kê nhưng không phải là thư mục — chẳng hạn không có gì tồn tại ở đó — sẽ bị cả hai lệnh từ chối trước khi bất cứ thứ gì được phân giải hoặc ghi, nêu tên mục đó cùng tệp cấu hình và dòng liệt kê nó, như Nơi đọc các entity cục bộ trình bày.
Cách quá trình phân giải tìm các đầu vào bên ngoài
Không điều gì trong phần này thay đổi quy tắc ở trên — vẫn chỉ có một thời điểm duy nhất mà bất cứ thứ gì được ghim, và đó là lệnh này. Phần này mô tả cách lệnh tiếp cận loại thứ ba trong ba loại, điều này quan trọng khi bạn đưa quá trình phân giải vào một pipeline, đọc một lần chạy bị suy giảm, hoặc lý giải vì sao lệnh này lại render.
Một entity trong catalog và một artifact nguồn đều được đặt tên trong một tài liệu; một đầu vào bên ngoài thì không. Phân giải hai loại đầu chỉ là việc đọc những gì bạn đã viết. Một đầu vào bên ngoài được đặt tên bởi một provider, giữa chừng một lần render, và những URL nó đặt tên phụ thuộc vào các giá trị đang được render — một mục values vắng mặt sẽ khiến cả một cây con trong schema của chart không được biên dịch và mọi tham chiếu từ xa trong cây con đó không được yêu cầu. Không lần đọc Release nào có thể liệt kê được tập hợp này.
Vì vậy lệnh làm hai việc trong một lượt: phân giải và ghim bao đóng mà các tài liệu đặt tên, rồi render bao đóng đó để xem các providers yêu cầu những tài liệu từ xa nào. Các artifact đã render bị bỏ đi và các pin được giữ lại. Cả hai đều nằm bên trong một lệnh duy nhất, và không cái nào là thời điểm thứ hai mà một thứ gì đó có thể được ghim — chỉ có một lần ghi lockfile, và nó chứa mọi pin.
Có hai hệ quả đáng biết trước khi đưa quá trình phân giải vào một pipeline tự động như một bước rẻ. Nó tốn kém hơn một lần phân giải chỉ đọc tài liệu, vì nó render. Và nó có thể thất bại vì một lý do mà phân giải chỉ đọc tài liệu không thể gặp: một provider không thể render Release này. Khi điều đó xảy ra, các pin phụ thuộc vẫn được ghi, vì không gì trong chúng phụ thuộc vào lần render, và chẩn đoán nêu tên giai đoạn đã dừng, những gì đã được ghim, và rằng một lần build sẽ dừng lại nêu tên URL chưa được ghim. Lần chạy không bị mất, và Offline cho thấy cùng kết quả đó đạt được theo một cách khác.
Lần render cũng đối chiếu lockfile với phép so sánh mà một lần build áp dụng, trước khi bất cứ thứ gì được ghi. Nó chạy chính trình tự của build, nên nó so sánh lockfile mà lệnh này sắp ghi với kết quả phân giải của một lần build cùng Release, đúng như một lần build so sánh một lockfile nó tìm thấy trên đĩa. Một lockfile bị phép so sánh đó từ chối sẽ không được ghi — cũng như mọi thứ khác lệnh lẽ ra sẽ ghi sau nó — và lệnh dừng lại, báo rằng quá trình phân giải và build không thống nhất về những gì Release phụ thuộc vào, kèm theo từng mục mà phép so sánh nêu tên. Không gì trong các tệp của bạn có thể gây ra điều đó, và phân giải lại sẽ đi đến cùng sự bất đồng, vì vậy hãy báo cáo nó kèm theo Release thay vì thử lại. Đây là lỗi render duy nhất làm dừng việc ghi, và là lý do một lần build cùng Release, trên cùng các đầu vào, không báo drift trên một lockfile do lệnh này ghi.
Không có công tắc nào để bỏ qua lần render. Một công tắc như vậy sẽ giữ lại, dưới dạng một tùy chọn, đúng sự bất ngờ mà một thời điểm duy nhất đã loại bỏ: một Release phân giải gọn gàng trong khi một đầu vào mà lần render của nó cần vẫn chưa được ghim, chỉ bị phát hiện lúc build.
--auto-pull gộp chính quá trình phân giải này vào một lần build, và lần build chỉ render một lần. Lần render của bước điền là lần tìm và ghim các đầu vào bên ngoài, và lần build trình bày lần render đó thay vì thực hiện lần thứ hai, nên một lần build bằng một lệnh tốn đúng một lần render như một lần build thông thường trên một lockfile đã được điền. aggrega build nêu rõ những cờ render nào của build đến được nó.
Tập hợp này phụ thuộc vào các parameters của Release, đó cũng là cách các pin component vốn hoạt động. Sửa parameters của một Release giữa lần phân giải và lần build là một chỉnh sửa đối với Release, nên lần build dừng lại ở phép so sánh drift, nêu tên tệp, trước khi bất kỳ lần render nào có thể yêu cầu một URL chưa được ghim; cách khắc phục là lệnh này. Các parameters được nhập từ một tệp riêng không được ghi lại theo nội dung, nên sửa tệp đó thay vào đó sẽ đi đến lần render, lần render này dừng lại nêu tên URL chưa được ghim — với cách khắc phục cũng nêu tên lệnh này.
Tính tất định và tính toàn vẹn
source: của một Recipe có thể dùng template cho phiên bản của nó dựa trên values và infra đã phân giải của Release (và trên các locals được định nghĩa trên chính Release đó); những giá trị này được phân giải tại thời điểm pull và kết quả được ghim. Lần pull chỉ đánh giá các mục locals: mà các trường source: đọc, cùng các mục mà những mục đó lần lượt đọc, và chỉ bằng các template helper riêng của Aggrega: một mục mà source đọc có gọi hàm Sprig sẽ dừng lần pull, nêu tên mục, trường và hàm đó, còn một mục không trường source: nào đọc thì được để lại cho build, nơi đánh giá và kiểm tra nó khi Recipe render — xem Resolving a source: coordinate registers a narrower function set (Việc phân giải một tọa độ source: đăng ký một tập hàm hẹp hơn). Một Git tag hoặc branch có thể thay đổi sẽ được ghim vào commit cụ thể mà nó trỏ tới, và ref bạn đã viết được ghi lại bên cạnh. Tại thời điểm build, digest của archive trong cache được xác minh lại với lockfile, nên một cache bị can thiệp sẽ bị phát hiện.
Một ref đã ghi lại được giữ cố định với commit mà nó đã ghim. Ref được ghi lại vì các lần chạy sau sẽ hỏi lại nó, chứ không phải để dễ đọc — một bản build hỏi nó chỉ tới artifact nào, và một lệnh pull hỏi liệu nó có còn trỏ tới chỗ cũ không. Một lệnh pull không phải là nâng cấp sẽ hỏi lại mỗi ref đã ghi xem nó trỏ tới đâu, và một ref đã di chuyển tại remote của nó sẽ dừng lần chạy — nêu tên artifact, ref, commit mà lockfile ghim và commit mà nó phân giải tới hiện nay — thay vì chấp nhận sự di chuyển đó. Chạy aggrega pull --upgrade --release <release> để chấp nhận nó. Một lần nâng cấp có chỉ định, vốn nêu tên các URI thực thể, thì không: một tham chiếu source không phải là một thực thể bạn có thể nêu tên, nên một lần chạy có chỉ định giữ nó y như một lệnh pull thông thường.
Việc kiểm tra đó là điều duy nhất mà bước xác minh lại digest lúc build không thể làm thay bạn. Một lệnh pull chấp nhận một ref đã di chuyển sẽ ghi lại các byte đã tải và digest đã ghi trong cùng một thao tác, nên hai giá trị mà bản build so sánh sẽ cùng thay đổi và khớp nhau — và bạn sẽ build trên nội dung source khác với nội dung mà lockfile đã được xem xét, mà không có gì báo cáo điều đó.
Chỉ ref mà lockfile ghi lại mới được giữ theo cách này, và một ref được ghi lại bất cứ khi nào bạn viết nó. Một Recipe chỉ nêu source của nó bằng version: thì không có ref, nên không có gì để lần chạy sau hỏi lại — đó là câu trả lời đúng, vì một phiên bản do chính bạn viết không thể thay đổi mà bạn không biết. Tài liệu tham khảo lockfile nêu rõ những gì được ghi lại.
Hãy viết ref, không phải commit. Một lệnh build tìm artifact lấy từ git theo ref bạn đã viết, so khớp với ref mà lockfile đã ghi, nên ref: v1.2.3 build trên commit mà tag đó đã được ghim vào và commit không bao giờ cần xuất hiện trong Recipe của bạn. Thay vào đó, nêu một tag có thể thay đổi trong version: sẽ không hoạt động và cũng không nhằm mục đích đó: version: được so khớp đúng như đã viết, và với một source git, lockfile ghim một commit.
Lockfile ghim nội dung được tải từ các registry và các source từ xa, và ghi lại digest của mỗi thực thể mà nó phân giải từ các thư mục catalog của bạn — trên tệp thực thể và mọi tệp mà nó nêu tên bên cạnh, như Lockfile mô tả — và của mỗi tệp Release mà quá trình phân giải đã đọc. Các tệp của một source bắt đầu bằng ./ hoặc ../, và một tệp artifact mà một thực thể nhập vào, cũng được ghim từng tệp một trong lock bên cạnh thực thể đó, như Lock của thực thể mô tả, đó là điều nêu tên tệp đã thay đổi; tính toàn vẹn của phần còn lại trong workspace của bạn giữa các lần build là trách nhiệm của hệ thống quản lý mã nguồn. Xem đầu ra giống hệt từng byte để biết phạm vi của bảo đảm về tính tất định.
Xác thực
Thông tin xác thực registry chỉ được đọc từ cấu hình thông tin xác thực Docker: config.json trong thư mục mà DOCKER_CONFIG chỉ định, hoặc ~/.docker/config.json khi biến đó không được đặt, cùng với mọi credential helper hoặc keychain của hệ điều hành mà tệp ủy quyền qua credsStore hoặc credHelpers. aggrega login <registry> ghi một thông tin xác thực vào đó, và docker login <registry> cũng vậy; hãy chạy một trong hai trước aggrega pull đối với một catalog OCI hoặc registry chart riêng tư. Các tệp mà podman login và helm registry login ghi không được đọc.
Một cấu hình thông tin xác thực không đọc được sẽ được báo cáo mà không tiết lộ nội dung của nó. Khi config.json không phải JSON hợp lệ, giá trị auth của một mục không phải là người dùng và mật khẩu nối bằng dấu hai chấm được mã hóa base64, hoặc một credential helper mà tệp nêu tên không thể trả lời, việc truy cập registry sẽ thất bại với thông báo nêu tên registry và tệp thông tin xác thực, nhưng không bao giờ nêu nội dung của tệp hay của mục. aggrega login và aggrega logout báo cáo một config.json không phải JSON hợp lệ theo cùng cách, và không thay đổi gì trong đó. Hãy sửa tệp; một mục không đọc được cũng có thể được thay thế bằng aggrega login <registry>.
Một kho Helm chart cổ điển hoặc một tệp lưu trữ chart (helm-https-chart), một đoạn compose (compose-https-fragment) và một kho Git được truy cập qua HTTP hoặc HTTPS (git-repository) xác thực bằng tệp netrc, tệp thông tin xác thực theo từng người dùng mà curl và Git cũng đọc. Đây là kho thông tin xác thực duy nhất mà ba loại này đọc: ~/.config/helm/repositories.yaml và các credential helper của Git không được đọc. Một kho Git được truy cập qua SSH xác thực thông qua SSH agent và không đọc tệp netrc nào.
machine charts.example.com login deploy-bot password <token>Tệp nào được đọc. Tệp mà biến môi trường NETRC chỉ định, khi biến này được đặt. Nếu không, là .netrc trong thư mục home của bạn; trên Windows, là _netrc trong %USERPROFILE% khi tệp đó tồn tại, và .netrc ở đó khi không tồn tại. Một tệp không tồn tại không chứa thông tin xác thực nào và không phải là lỗi. Một tệp tồn tại nhưng không đọc được, hoặc không theo định dạng netrc, sẽ dừng lệnh với E0360, nêu tên tệp — và, với lỗi định dạng, cả dòng — nhưng không bao giờ nêu nội dung tệp: The netrc file cannot be read (Không thể đọc tệp netrc). Trên Linux và macOS, một tệp netrc mà những người dùng khác trên máy có thể đọc sẽ gây ra một cảnh báo nêu tên nó; hãy đặt để chỉ bạn đọc được (chmod 600).
Mục nào trả lời một yêu cầu. Mỗi yêu cầu được tra cứu theo host của nó — tên host không kèm cổng, không phân biệt chữ hoa chữ thường — và được trả lời bởi mục machine đầu tiên nêu tên host đó, hoặc bởi mục default khi không có mục nào. login và password của mục được gửi dưới dạng thông tin xác thực HTTP basic, qua cả http lẫn https; một mục thiếu một trong hai sẽ không gửi gì. Một kho có index đặt các chart của nó trên một host khác được trả lời theo từng yêu cầu: yêu cầu index lấy mục của host kho, còn yêu cầu chart lấy mục của host chart. Một yêu cầu đi mà không có thông tin xác thực phải đọc được ẩn danh, và một máy chủ trả lời 401 hoặc 403 sẽ dừng lần pull như một lần tải không được phép, với cách khắc phục nêu tên mục cần thêm và tệp đã được tìm trong đó.
Thông tin xác thực không được ghi ở đâu cả. Nó được đọc khi một lần tải chạy và được gửi kèm yêu cầu: lockfile, entity.lock bên cạnh Recipe, cache nguồn và mọi thông báo đều mang URL của nguồn đúng như bạn đã viết.
URL nguồn không mang thông tin xác thực. Một Recipe hoặc FeatureRecipe có url nguồn ghi một người dùng trước host — https://user:token@charts.example.com/…, hoặc một token được viết riêng như https://token@charts.example.com/… — sẽ bị từ chối với E0361 khi tài liệu được đọc, trước khi bất cứ thứ gì được tải: việc xác thực Recipe từ chối nó, và mọi lần pull, pin và build chạm tới nó cũng vậy. Thông báo nêu tên host và không bao giờ nêu thông tin xác thực: A source URL carries a credential (URL nguồn mang thông tin xác thực). Thay vào đó, hãy đặt thông tin xác thực vào một mục machine của tệp netrc. Qua SSH, một người dùng được viết riêng — ssh://git@github.com/… — chỉ định một tài khoản chứ không phải một bí mật và được chấp nhận, trong khi một mật khẩu được viết ở đó cũng bị từ chối.
Việc kiểm tra chỉ đọc phần URL trước host. Một token nằm trong chuỗi truy vấn hoặc đường dẫn — …/index.yaml?access_token=… — không bị phát hiện, vì vậy đừng viết token ở đó: URL được ghi lại đúng như đã viết trong lockfile, trong entity.lock và trong cache nguồn, kể cả tên các thư mục của cache.
Biến môi trường
Các thiết lập workspace mà pull đọc có thể được ghi đè qua môi trường, ở mức trên cấu hình đã commit và dưới mọi cờ: AGGREGA_OFFLINE (xem Ngoại tuyến, và --offline cho cờ ở mức trên nó), AGGREGA_CATALOG_DIRS (phân tách theo kiểu danh sách đường dẫn của hệ điều hành; hãy cung cấp đường dẫn tuyệt đối), AGGREGA_ARTIFACT_CACHE_DIR, AGGREGA_DEFAULT_REGISTRY, và AGGREGA_SKIP_SIGNATURE_VERIFICATION (có cảnh báo rõ ràng — ở bất cứ đâu mà một lần pull lẽ ra đã kiểm tra chữ ký, nó ghi một cảnh báo rằng việc xác minh bị tắt trên toàn cục). Xem environment-variables.md để biết danh sách đầy đủ và mô hình thứ tự ưu tiên.
Xem thêm
- ./aggrega-build.md — kiểm tra lockfile và tự động pull khi được cấu hình.
- ./aggrega-serve.md — daemon thực hiện cùng quá trình phân giải này tại
aggrega/resolveDependencies, và bên trongaggrega/buildcho một yêu cầu có trườngautoPullyêu cầu điều đó, để trình soạn thảo có thể chạy nó mà không rời phiên làm việc; dù theo cách nào, nó chỉ chạy khi một yêu cầu chỉ định nó, và ghi cùng một lockfile như lệnh này. - ./aggrega-push.md — xuất bản các thực thể catalog lên một registry.
- ./aggrega-lint.md — cổng kiểm tra xuất bản chạy trước
aggrega push. - ../../architecture/13-catalog-and-registry.md — mô hình catalog, lockfile và bộ nhớ đệm đầy đủ.
Cú pháp
aggrega pull [<uri>...] [flags]Mô tả
Resolve the Release's catalog and source dependencies into the cache and write the per-Release lockfile.
By default, pull reconciles the lockfile against the current dependency resolution while honoringthe pins it already records. That pin discipline governs what a registry or the content cacheserves: such an entity is fetched at its pinned version and verified against its pinned digest,and if the registry no longer serves the pinned bytes, pull halts rather than silently re-pinning.An entity a local catalog directory supplies is resolved from that directory instead, at theversion its file declares, and its recorded pin is not consulted — so editing a pin by hand doesnot hold a locally-supplied entity at that version, and the reconcile rewrites the entry to matchthe file. A reference with no pin — newly added, or removed from the lockfile by hand — isresolved fresh and added. Entities no longer among the resolved dependencies are pruned.Re-running pull on an unchanged dependency set is a no-op.
Use --upgrade with no positional arguments to discard the existing lockfile and re-resolveevery entity from current registry state, floating each dependency to the highest availableversion. That form drops every recorded pin, so it asks for confirmation first; --yes answers inadvance, and on a non-interactive stdin it refuses rather than waiting for an answer nobody cangive. Pass one or more entity URIs after --upgrade to upgrade only those: each named pinis dropped and re-resolved fresh while every other pin — and the recorded external inputs —is held unchanged. A named target may also be a plugin that returns an accept-or-reject verdict;such a plugin carries no lockfile pin, and its identity is recorded beside the lockfile instead.Naming one the workspace still attaches adopts the identity it resolves to. Naming one theworkspace no longer attaches drops its recorded identity — the one way to clear an entry thatoutlived the attachment it was recorded for. A bare --upgrade does both for every plugin at once.A URI given without --upgrade is a usage error.
Each Recipe and FeatureRecipe this Release builds from one of your catalog directories carriesthe pins for its own inputs in the entity.lock beside it: a remote source: written out in full,a file an artifacts entry imports, and each file of a local source:. Recording them is theentity author's step, aggrega pin.By default pull records none of them, and halts on an entity whose lock is missing any, namingthe entity, each input and its class, and the command that records them. A local source's filesare held to their pins as one set: a file added, changed or removed since the pin halts the pullthe same way.Pass --pin-sources, or set pin_sources_at_pull in the workspace configuration, to have pull runthat same step instead; --pin-sources=false restores the halt for one run.
Which files of a local source directory belong to its entity was decided when the entity waspinned, by the ignore rules of the plugin that served its capability for the author, and itsentity.lock records that decision. Where the plugin this workspace binds for that capabilitydeclares different rules, pull prints a warning naming both plugins and the difference, andcarries on: the entity's files are the ones its recorded rules kept.Cờ
| Cờ | Mặc định | Mô tả |
|---|---|---|
--catalog | [] | Thư mục catalog; có thể lặp lại. Mỗi —catalog <dir> được thêm vào đầu ngăn xếp tìm kiếm catalog (kết quả khớp đầu tiên được dùng): catalog_dirs của workspace, hoặc, với một Release mà cấu hình workspace cấp thư mục riêng trong workspace.releases, thì các thư mục của Release đó; ngăn xếp kết thúc bằng thư mục có tên catalog ở gốc workspace nếu có. Một danh sách catalog_dirs được viết rỗng sẽ không đọc catalog cục bộ nào cả. |
--detail | false | In ra, cho từng thực thể đã phân giải, những gì lần pull này đã làm — tải mới từ một registry, dùng lại một ô bộ nhớ đệm, tìm thấy trong một catalog cục bộ, cung cấp từ bên trong tệp nhị phân của trình biên dịch, hoặc bên ngoài (Aggregate hoặc Manifest riêng của Release, đọc từ tệp hoặc mục mà Release chỉ định). Chỉ ra stdout; không ghi vào lockfile |
--dry-run | false | Phân giải các phụ thuộc và in ra những gì lần pull này sẽ ghi thay vì ghi chúng: đường dẫn của từng tệp và nội dung nó sẽ chứa được đưa ra stdout, còn lockfile, entity.lock bên cạnh mỗi Recipe và FeatureRecipe có các pin đã ghi sẽ thay đổi dưới —pin-sources, và bản ghi tin cậy plugin đều được giữ nguyên. Chỉ những tệp thực sự sẽ thay đổi mới được nêu tên. Bản thân quá trình phân giải chạy đúng như bình thường, nên bộ nhớ đệm nội dung vẫn được điền, một lần pull sẽ dừng ở một thực thể chưa được pin thì cũng dừng ở đây, và một —upgrade không kèm đối số không hỏi gì vì nó không bỏ pin nào — những gì một lần chạy thử hiển thị chính là những gì một lần pull sẽ ghi. Không được chấp nhận cùng —verify, vốn đã không ghi tệp nào trong số đó |
--include-prerelease | false | Chưa được triển khai: được chấp nhận và bỏ qua, để một script truyền cờ này vẫn hoạt động khi nó bắt đầu có tác dụng |
--pin-sources | false | Chạy bước pin của tác giả thực thể trên các Recipes và FeatureRecipes mà Release này xây dựng, ghi vào entity.lock bên cạnh mỗi thực thể pin cho mọi đầu vào nó đọc — một nguồn từ xa: được viết đầy đủ, một tệp mà một mục artifacts nhập vào, và từng tệp của một nguồn cục bộ — thay vì dừng ở một thực thể có lock không ghi lại chúng. Cùng bước với aggrega pin, ghi cùng các byte. Nó ghi bên cạnh thực thể, nên chỉ chạy ở nơi thực thể có chỗ ghi được: một tài liệu trong một trong các thư mục catalog của bạn. Một thực thể được phân giải từ bộ nhớ đệm không có chỗ như vậy và không bao giờ được pin. Ghi đè pin_sources_at_pull của workspace theo cả hai chiều: —pin-sources pin cho lần chạy này và —pin-sources=false dừng cho lần chạy này, bất kể thiết lập là gì |
--progress | false | Buộc bật giao diện tiến trình pull ngay cả khi stderr không phải là terminal, in một dòng văn bản thuần cho mỗi bước khi nó hoàn thành, kèm thời gian. Mặc định là auto: danh sách kiểm tra các giai đoạn dạng tương tác chỉ hiển thị khi stderr là một terminal diễn giải được chuỗi escape, một terminal không diễn giải được sẽ nhận cùng các dòng văn bản thuần, và đầu ra được chuyển hướng hoặc qua pipe thì không nhận gì |
--quiet | false | Tắt giao diện tiến trình pull trên stderr. Không ảnh hưởng đến stdout. Được ưu tiên hơn —progress |
--release | — | Đường dẫn đến tệp YAML của Release (bắt buộc). Đường dẫn tương đối được phân giải theo thư mục bạn chạy lệnh, không theo gốc workspace. Khi thư mục đó không thuộc workspace nào và không có gốc nào được chỉ định, một đường dẫn tuyệt đối sẽ tìm workspace từ thư mục riêng của Release |
--upgrade | false | Phân giải lại các phụ thuộc từ trạng thái hiện tại của registry, nâng mỗi phụ thuộc lên phiên bản cao nhất có sẵn. Khi không kèm đối số (không có URI vị trí), bỏ lockfile và phân giải lại mọi thực thể, đồng thời hỏi xác nhận trước vì nó bỏ mọi pin đã ghi; với một hoặc nhiều URI thực thể, chỉ phân giải lại những thực thể đó, giữ nguyên mọi pin khác và các đầu vào bên ngoài đã ghi, và không hỏi gì (loại trừ lẫn nhau với —verify) |
--verify | false | Kiểm tra lockfile hiện có so với quá trình phân giải phụ thuộc mà một lần pull sẽ thực hiện lúc này, mà không ghi lockfile, bản ghi tin cậy plugin hay bất kỳ entity.lock nào; thoát với mã khác 0 khi có sai lệch hoặc thiếu lockfile. Quá trình phân giải tôn trọng các pin mà lockfile ghi đúng như một lần pull: một tham chiếu có registry đã xuất bản phiên bản mới hơn kể từ lần pull không phải là sai lệch, vì một lần pull sẽ giữ pin của nó, và một registry nay cung cấp các byte khác dưới một phiên bản đã pin sẽ dừng lần kiểm tra như nó dừng một lần pull. Bộ nhớ đệm nội dung được đọc và điền như một lần pull đọc và điền: một mục mà bộ nhớ đệm giữ dưới pin của nó được đọc từ đó mà không hỏi registry, một mục không có thì được tải về, và một mục không còn khớp với pin được xử lý đúng như một lần pull xử lý. Đồng thời đối chiếu entity.lock bên cạnh mỗi Recipe và FeatureRecipe trong các thư mục catalog của bạn mà Release chạm tới với những gì một lần build so sánh, và thoát với mã khác 0 khi có một pin mà build sẽ từ chối: một tệp được nhập không còn khớp với digest đã ghi, một nguồn cục bộ có các tệp không còn khớp với digest đã ghi, hoặc một pin nguồn mâu thuẫn với lockfile. Đồng thời so sánh chữ ký mà lockfile ghi cho mỗi artifact, và bản ghi tin cậy plugin cho mỗi plugin, với cái mà một lần pull sẽ ghi lúc này, và thoát với mã khác 0 ở chỗ một lần pull sẽ ghi, thay thế hoặc xóa một cái: một chữ ký mà một yêu cầu đòi hỏi nhưng chưa được ghi, và một chữ ký được tạo cho artifact khác, được báo cáo mà không hỏi registry, vì một lần pull ghi lại chúng bất kể registry trả lời gì; một chữ ký mà một lần pull tra cứu lại và có thể ghi không đổi — artifact đã được tải về, hoặc gói chữ ký trong bộ nhớ đệm của nó đã bị xóa hoặc thay đổi — được hỏi tại registry của nó, hoặc ở chế độ offline thì không được kiểm tra, kèm một dòng thông báo như vậy; và mỗi plugin mà bản ghi tin cậy plugin bao gồm được kiểm tra tại registry của nó, như mọi lần pull đều kiểm tra, trừ ở chế độ offline, khi đó nó được đọc từ bộ nhớ đệm nội dung như một lần build đọc, danh tính và các hàm host của nó vẫn được kiểm tra, còn chữ ký không được kiểm tra, kèm một dòng thông báo như vậy, trừ khi một lần build từ chối nó vì không ghi chữ ký nào hoặc ghi chữ ký được tạo cho artifact khác, trường hợp này được báo cáo. Các dấu hiệu ngừng hỗ trợ không được so sánh. Đồng thời báo cáo phiên bản trình biên dịch và core-plugin mà lockfile ghi — chỉ báo cáo để kiểm toán và không bao giờ so sánh với tệp nhị phân này, nên khác biệt về toolchain không bao giờ là sai lệch. Không được chấp nhận cùng —pin-sources, bất kể giá trị nào: một lần kiểm tra không ghi pin mà entity.lock còn thiếu và cũng không dừng vì nó, nên cờ này sẽ không thay đổi gì (loại trừ lẫn nhau với —upgrade) |
--yes | false | Trả lời trước lời xác nhận của —upgrade không kèm đối số, để dùng không tương tác. Nó chỉ tác động đến đúng lời nhắc đó và không gì khác: mọi dạng pull khác đều không hỏi gì, nên truyền cờ này ở đó không thay đổi hành vi nào |