Schema Entity Lock của Aggrega
Tài liệu tham khảo được sinh tự động. Không chỉnh sửa thủ công — hãy sinh lại từ JSON Schema đã xuất bản.
Id của schema: https://aggrega.ai/schemas/entity-lock-v1beta1.schema.json
Tệp entity.lock nằm cạnh một thực thể và ghi lại các ghim nội dung cho những đầu vào mà thực thể đó lấy từ bên ngoài tài liệu của chính nó: các tệp mà artifact của nó import, các tệp của một nguồn cục bộ, và các nguồn từ xa có danh tính được thực thể viết ra đầy đủ — và, với một nguồn cục bộ là thư mục, các quy tắc quyết định những tệp nào trong đó thuộc về thực thể. Một bước duy nhất ghi tệp này: aggrega pin, do tác giả của thực thể chạy và không cần Release nào. aggrega pull và aggrega push chạy chính bước đó, và ghi ra đúng các byte đó, khi được yêu cầu — bằng --pin-sources, hoặc bằng pin_sources_at_pull hay pin_sources_at_push của workspace. Một lần pull không được yêu cầu ghim thì không ghi gì vào đây: trên một thực thể nằm trong các thư mục catalog của chính workspace, nó so sánh những gì bước đó sẽ ghi lại với những gì tệp đang chứa, và dừng lại, nêu tên aggrega pin, khi một ghim bị thiếu hoặc không còn khớp với đầu vào của nó — với một nguồn cục bộ, một tệp được thêm, thay đổi hoặc xóa kể từ lần ghim sẽ làm dừng lần pull như mọi ghim lỗi thời khác. aggrega build đọc lại tệp này và dừng khi những gì có trên đĩa không còn cho ra digest đã được ghi lại. Phạm vi của tệp được xác định bởi thư mục chứa nó — nó ghim các đầu vào của thực thể trong thư mục đó — nên một tên tệp dùng được cho mọi loại thay vì mỗi loại mang một cách viết riêng. Bước này xóa lock của một thực thể không đọc đầu vào nào như vậy, thay vì để lại một lock rỗng. Bản thân tài liệu thực thể không bao giờ được máy ghi: những gì tác giả gõ vẫn giữ nguyên như đã gõ, còn những gì máy suy ra nằm ở đây. Sự tách biệt đó giúp lock an toàn để commit và dễ đọc dưới dạng diff, vì mỗi hàng nêu một đầu vào và một digest thay đổi cho biết đầu vào nào đã thay đổi. Tệp không chứa dấu thời gian và không chứa siêu dữ liệu phân giải, nên chạy lại bước này trên các đầu vào không đổi sẽ giữ tệp giống hệt từng byte. Một dạng hàng duy nhất dùng cho mọi loại có thể ghi một ghim, nên một ghim được đọc giống hệt nhau dù thuộc loại nào. Dạng wire là đóng (additionalProperties: false). Nguyên tắc tiến hóa schema: thêm một trường tùy chọn mới là SemVer-MINOR (bổ sung); xóa một trường hoặc thắt chặt một ràng buộc là SemVer-MAJOR.
Kiểu cấp cao nhất: object
Thuộc tính
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
version | const 1 | có | Phiên bản schema của entity-lock: 1. Một thay đổi SemVer-MAJOR của schema sẽ tăng giá trị này. Hằng số: 1 |
sourceDigests | object[] | không | Các ghim nội dung cho những nguồn từ xa mà thực thể này tham chiếu và có định danh được thực thể viết ra đầy đủ, được cố định khi phân giải từ các byte đã tải về và được đọc lại khi build để xác minh nguồn trong bộ nhớ đệm không bị sai lệch. Mỗi mục phản ánh định danh nguồn đã phân giải {kind, url, chart, moduleSubdir, version} cùng với digest nội dung (và, với một nguồn phân phối qua OCI, digest của manifest). Một nguồn có định danh được điền từ một template — ví dụ một phiên bản đọc từ các giá trị hạ tầng của một Release — không có mục nào ở đây: artifact mà nó chỉ định được quyết định bởi từng Release sử dụng thực thể, vì vậy mỗi định danh mà nó phân giải thành sẽ được ghim trong lockfile của Release đó. Một nguồn cục bộ (tương đối theo hệ thống tệp) cũng không có mục nào ở đây: nó chỉ định một đường dẫn chứ không phải thứ được tải về, nên không có kho lưu trữ nào để ghim, và thay vào đó các tệp của nó được ghim từng tệp một trong localSourceDigests. |
artifactDigests | object[] | không | Các ghim nội dung cho những tệp mà các artifact của thực thể này import qua $import — với một Recipe, cả những tệp mà các mục boundary.artifacts của nó import — được cố định khi phân giải và được đọc lại khi build để xác minh tệp được import không bị sai lệch. Mỗi artifact có giá trị là một import tệp ứng với một mục; một artifact nội tuyến (literal) vốn đã là một phần của thực thể và không có ghim riêng, còn một artifact lấy từ một thư viện được ghim bằng phiên bản mà thư viện đó đã phân giải. Một bản build so sánh một mục của bất kỳ khối nào với ghim của nó theo cùng một cách, và từ chối một tệp không còn khớp với ghim theo cùng điều kiện. |
localSourceDigests | object[] | không | Các ghim nội dung cho các tệp của nguồn cục bộ của thực thể này — một nguồn được viết dưới dạng đường dẫn bên cạnh thực thể thay vì được tải về — được cố định khi thực thể được ghim và được đọc lại khi build để xác minh các tệp không bị sai lệch. Mỗi tệp mà nguồn đóng góp vào nội dung một bản phát hành của thực thể mang theo ứng với một mục: mọi tệp nằm dưới thư mục mà nguồn chỉ định được các quy tắc ghi dưới ignore giữ lại, hoặc một tệp duy nhất mà nó chỉ định. Một nguồn cục bộ viết dưới dạng template chỉ chỉ định thư mục của nó khi một Release điền template đó, nên nó đóng góp mọi tệp trong chính thư mục của thực thể mà các quy tắc đã ghi giữ lại, và mỗi tệp đó đều được ghim. Tài liệu thực thể, tệp .aggregaignore của tác giả bên cạnh nó và tệp này không bao giờ là mục: tài liệu chính là thực thể, các quy tắc của tệp ignore được ghi dưới ignore, và lock không thể ghi digest của chính nó. Một khi lock ghi bất kỳ mục nào ở đây, một bản build sẽ từ chối một nguồn chứa một tệp không có mục, một tệp có nội dung không còn cho ra digest khớp với mục của nó, hoặc thiếu một tệp mà một mục chỉ định. |
ignore | object | không | Các quy tắc quyết định những tệp nào dưới thư mục nguồn cục bộ của thực thể này thuộc về nó, được ghi lại khi thực thể được ghim. Mọi lần đọc thư mục đó về sau đều áp dụng các quy tắc này và không gì khác: một bản phát hành của thực thể, phép so sánh mà một lần pull hoặc một bản phát hành đối chiếu với lock, dòng thực thể của tác giả, phép so sánh và kết xuất của một bản build, và một lần pull có xác minh. Vì vậy, một thay đổi đối với tệp .aggregaignore của tác giả, đối với liên kết provider của workspace hoặc đối với tệp nhị phân aggrega sẽ không làm thay đổi digest nào cho đến khi thực thể được ghim lại, và việc ghim lại sẽ hiển thị thay đổi đó ở đây dưới dạng một diff. Chỉ có mặt khi thực thể khai báo một nguồn cục bộ là một thư mục, hoặc một nguồn được viết dưới dạng template. Một lock không ghi quy tắc nào sẽ giữ lại mọi tệp dưới thư mục đó. Một liên kết tượng trưng ở bất kỳ đâu bên dưới nó sẽ bị từ chối thay vì được đi theo. |
Không cho phép thuộc tính bổ sung.
entity-lock.sourceDigests[]
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
kind | enum | có | Loại nguồn đã phân giải. Là một giá trị trong một tập đóng — cùng tập mà kind của source-artifact trong lockfile và kind của siêu dữ liệu bộ nhớ đệm mang — vì cả ba đều ghi cùng các định danh nguồn đã phân giải và một bản build đọc loại này để chọn trình nạp. terraform-module-oci thuộc tập này, và không adapter nguồn nào phục vụ nó: một Recipe hoặc FeatureRecipe nêu nó sẽ bị từ chối ngay khi được đọc. Giá trị cho phép: "helm-oci-chart", "helm-https-chart", "compose-https-fragment", "git-repository", "terraform-module-oci" |
url | string | có | URL nguồn do tác giả viết mà digest ghim — URL định danh như được viết trong spec.source.url (gốc của một repo hoặc một tệp .tgz trực tiếp với helm-https-chart). Build dựng lại chính URL này khi ngoại tuyến, nên đây là định danh ổn định làm khóa cho ghim, không phải vị trí artifact đã phân giải. |
chart | string | không | Tên chart của một nguồn helm dạng gốc repo (spec.source.chart), là một phần của định danh nguồn đã phân giải để hai chart được phục vụ từ cùng một gốc repo ở cùng phiên bản được ghim riêng biệt. Vắng mặt với một nguồn .tgz trực tiếp, OCI, compose hoặc git, vì không nguồn nào trong số đó chọn một chart bên trong URL. |
moduleSubdir | string | không | Thư mục bên trong một kho lưu trữ lấy từ git chính là artifact (spec.source.module_subdir), là một phần của định danh nguồn đã phân giải để hai thư mục của cùng một kho lưu trữ ở cùng commit được ghim riêng biệt. Vắng mặt khi toàn bộ kho lưu trữ là artifact, và với mọi loại tiếp cận artifact của nó qua URL thay vì đi xuống bên trong một bản clone. |
version | string | có | Phiên bản cụ thể đã ghim mà nguồn phân giải thành — một phiên bản chart với loại helm-*, commit mà một tham chiếu git-repository phân giải thành. Được ghi dưới dạng một đoạn đường dẫn duy nhất, vì nó tạo nên ô bộ nhớ đệm mà bản build đọc lại nguồn từ đó, nên nó không chứa /, \ hay ... Mẫu: ^([^/\\.]|\.[^/\\.])*\.?$. |
digest | string | có | Digest nội dung của kho lưu trữ nguồn đã tải về, ở dạng sha256: theo sau là 64 ký tự hex chữ thường, được xác minh với các byte trong bộ nhớ đệm khi build. Mẫu: ^sha256:[a-f0-9]{64}$. |
manifestDigest | string | không | Digest của manifest OCI với một nguồn phân phối qua OCI — gốc tin cậy độc lập — ở dạng sha256: theo sau là 64 ký tự hex chữ thường. Chỉ có mặt với một nguồn OCI (một helm-oci-chart); vắng mặt với một nguồn https hoặc git, vốn theo cấu tạo không mang manifest. Mẫu: ^sha256:[a-f0-9]{64}$. |
Không cho phép thuộc tính bổ sung.
entity-lock.artifactDigests[]
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
name | string | có | Tệp $import của artifact nào được mục này ghim: khóa của map artifacts: với một mục của artifacts, và boundary/ theo sau là khóa với một mục của boundary.artifacts trong một Recipe — nhờ vậy các mục của mỗi khối được viết dưới cùng một khóa được ghim tách biệt. |
digest | string | có | Digest nội dung của các byte trong tệp được import, ở dạng sha256: theo sau là 64 ký tự hex chữ thường, được xác minh khi build. Mẫu: ^sha256:[a-f0-9]{64}$. |
Không cho phép thuộc tính bổ sung.
entity-lock.localSourceDigests[]
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
path | string | có | Đường dẫn của tệp tương đối so với thư mục chứa tài liệu thực thể, viết bằng dấu gạch chéo xuôi — ví dụ charts/app/templates/deployment.yaml. |
digest | string | có | Digest nội dung của các byte trong tệp, ở dạng sha256: theo sau là 64 ký tự hex chữ thường, được xác minh khi build. Mẫu: ^sha256:[a-f0-9]{64}$. |
Không cho phép thuộc tính bổ sung.
entity-lock.ignore
Các quy tắc quyết định những tệp nào dưới thư mục nguồn cục bộ của thực thể này thuộc về nó, được ghi lại khi thực thể được ghim. Mọi lần đọc thư mục đó về sau đều áp dụng các quy tắc này và không gì khác: một bản phát hành của thực thể, phép so sánh mà một lần pull hoặc một bản phát hành đối chiếu với lock, dòng thực thể của tác giả, phép so sánh và kết xuất của một bản build, và một lần pull có xác minh. Vì vậy, một thay đổi đối với tệp .aggregaignore của tác giả, đối với liên kết provider của workspace hoặc đối với tệp nhị phân aggrega sẽ không làm thay đổi digest nào cho đến khi thực thể được ghim lại, và việc ghim lại sẽ hiển thị thay đổi đó ở đây dưới dạng một diff. Chỉ có mặt khi thực thể khai báo một nguồn cục bộ là một thư mục, hoặc một nguồn được viết dưới dạng template. Một lock không ghi quy tắc nào sẽ giữ lại mọi tệp dưới thư mục đó. Một liên kết tượng trưng ở bất kỳ đâu bên dưới nó sẽ bị từ chối thay vì được đi theo.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
plugin | object | không | Plugin đã phục vụ capability của thực thể trong workspace của tác giả khi thực thể được ghim — binding provider của workspace cho capability đó, hoặc nếu không có thì là plugin tích hợp sẵn trong binary aggrega — được nêu tên không kèm phiên bản, cùng các quy tắc ignore mà nó đã khai báo. Không phiên bản và không digest nào của plugin được ghi lại: các quy tắc là thứ mọi lần đọc áp dụng, nên việc ghim lại dưới một bản phát hành khác của cùng plugin sẽ giữ nguyên lock trừ khi các quy tắc thay đổi. Một lần pull có plugin riêng cho capability đó khai báo các quy tắc khác sẽ báo điều này trong một thông báo tư vấn, nêu tên cả hai plugin và điểm khác biệt, và không bao giờ dừng lại vì điều đó. Không có khi không plugin nào phục vụ capability. |
rules | object[] | không | Các quy tắc được tổng hợp chính xác, theo thứ tự áp dụng: các mẫu của plugin, sau đó là các dòng của mọi tệp ignore mà plugin nêu tên và quá trình duyệt tìm thấy, tệp của chính một thư mục đứng trước các tệp bên dưới nó, rồi đến các dòng của tệp .aggregaignore của tác giả nằm cạnh thực thể. Một kết quả khớp sau ghi đè kết quả khớp trước, nên tệp của tác giả có tiếng nói cuối cùng đối với mọi đường dẫn mà nó nêu, và một dòng bắt đầu bằng ! sẽ đưa trở lại những gì một quy tắc trước đó đã loại trừ. Một thư mục bị quy tắc loại trừ sẽ không được duyệt vào, nên một tệp bên dưới nó chỉ được đưa trở lại khi thư mục đó được đưa trở lại. |
Không cho phép thuộc tính bổ sung.
entity-lock.ignore.plugin
Plugin đã phục vụ capability của thực thể trong workspace của tác giả khi thực thể được ghim — binding provider của workspace cho capability đó, hoặc nếu không có thì là plugin tích hợp sẵn trong binary aggrega — được nêu tên không kèm phiên bản, cùng các quy tắc ignore mà nó đã khai báo. Không phiên bản và không digest nào của plugin được ghi lại: các quy tắc là thứ mọi lần đọc áp dụng, nên việc ghim lại dưới một bản phát hành khác của cùng plugin sẽ giữ nguyên lock trừ khi các quy tắc thay đổi. Một lần pull có plugin riêng cho capability đó khai báo các quy tắc khác sẽ báo điều này trong một thông báo tư vấn, nêu tên cả hai plugin và điểm khác biệt, và không bao giờ dừng lại vì điều đó. Không có khi không plugin nào phục vụ capability.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
name | string | có | Plugin đã phục vụ capability của thực thể khi thực thể được ghim, ở dạng <pluginType>/<name>, không kèm phiên bản: các quy tắc bên dưới là thứ một lần đọc áp dụng, còn tên cho biết chúng là của ai. Dài ít nhất 1 ký tự. |
patterns | string[] | không | Các mẫu ignore mà plugin đã khai báo, đúng như nó đã khai báo. |
files | string[] | không | Tên các tệp ignore mà plugin đã khai báo là hệ sinh thái của nó tuân theo bên trong một nguồn. |
Không cho phép thuộc tính bổ sung.
entity-lock.ignore.rules[]
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
pattern | string | có | Một mẫu ignore theo cú pháp gitignore. |
within | string | có | Thư mục mà mẫu áp dụng trong phạm vi đó, tương đối so với thư mục chứa tài liệu thực thể và được viết bằng dấu gạch chéo xuôi; . chỉ chính thư mục đó. Một mẫu do plugin khai báo có phạm vi là thư mục nguồn cục bộ, một dòng của tệp ignore có phạm vi là thư mục chứa tệp đó, và một dòng của tệp .aggregaignore của tác giả có phạm vi là thư mục của thực thể. |
from | string | có | Nơi mẫu được khai báo: plugin đối với mẫu do plugin khai báo, và nếu không thì là đường dẫn của tệp ignore mà mẫu được đọc từ đó, tương đối so với thư mục chứa tài liệu thực thể. |
Không cho phép thuộc tính bổ sung.