aggrega pull
aggrega pull은 Release의 모든 의존성을 해석하고, 모든 의존성을 정확한 버전과 콘텐츠 다이제스트로 고정하는 lockfile을 작성합니다. 이후의 aggrega build는 lockfile이 고정한 것을 사용하고, 이를 검증하며, 필요한 것 중 lockfile에 고정되지 않은 것이 있으면 그 이름을 밝히며 중단합니다. 따라서 빌드는 재현 가능하며 오프라인에서도 수행할 수 있습니다.
빌드가 소비하는 모든 것은 이 한 시점에 고정됩니다. 카탈로그 엔터티, Recipe가 provider에 지정하는 소스 아티팩트, 그리고 provider가 렌더링 중에 요청하는 원격 문서는 같은 명령으로 해석되고 같은 lockfile 쓰기에 기록됩니다. 네트워크에 접근하는 단계는 aggrega pull이며, build는 접근하지 않습니다. 규칙은 이것이 전부이며, 이 페이지의 나머지 내용은 여기에서 비롯되는 결과입니다.
동작
aggrega pull은 세 종류의 의존성을 한 번에 해석합니다:
- 카탈로그 엔터티 — Release가 참조하는 Components, Features, Recipes, FeatureRecipes, 스키마 및 매핑 라이브러리, Wasm 플러그인입니다. 이들은 (
extends:,implements:,aggregate:, Feature 첨부, 라이브러리의$import:/$ref:위치를 통해) 전이적으로 해석되며, 아직 로컬에 없으면 레지스트리에서 가져옵니다. - 소스 아티팩트 — 개별 Recipe 또는 FeatureRecipe가 provider에 지정하는 원격
source:로, Helm 차트(OCI 또는 기존 HTTPS) 또는 HTTPS를 통한 Compose 프래그먼트입니다. 각각을 가져오고, 캐시하고, 고정합니다. - 외부 입력 — provider가 렌더링 중에 호스트에 요청하는 원격 문서로, 예를 들어 차트의
values.schema.json에서 URL을 가리키는$ref가 있습니다. 각각을 가져오고, 콘텐츠 다이제스트 아래에 저장하고, 고정합니다.
세 가지 중 두 가지는 작성한 문서에서 읽어 냅니다. 세 번째는 그렇지 않습니다. 외부 입력은 Release를 렌더링해야 찾을 수 있으며, 이 명령이 렌더링을 수행하는 이유가 여기에 있습니다. 명령을 실행하는 데에는 이 내용이 필요하지 않습니다. 렌더링의 비용, 렌더링을 완료할 수 없을 때 일어나는 일, 자체 lockfile을 채우는 빌드와의 관계를 포함한 전체 내용은 외부 입력을 해석이 찾는 방법에서 다룹니다.
레지스트리 없이 이름이 지정된 카탈로그 엔터티는 워크스페이스의 default_registry를 통해 가져오며, 기본값이 가진 리포지토리 경로가 가져오는 위치입니다. default_registry: ghcr.io/acme인 경우 core/api-server는 ghcr.io/acme/component/core/api-server에서 가져오며, 이곳은 aggrega push가 같은 기본값을 통해 게시하는 위치이고, 서명도 그곳에서 찾습니다. 경로는 위치일 뿐입니다. pull이 요구하는 서명, 신뢰하는 키와 ID, 제시하는 자격 증명은 호스트에 대해 보관된 것이므로, ghcr.io에 대한 registries 항목이 해당 호스트의 모든 경로를 관장합니다. lockfile은 이러한 엔터티를 호스트만으로 가져온 엔터티와 마찬가지로 ID, 버전, 다이제스트로 기록합니다. 경로의 표기법은 레지스트리 호스트를 작성하는 방법에 설명되어 있습니다.
결과는 Release 옆의 <release-stem>.lock에 작성됩니다. 수락 또는 거부 판정을 반환하는 플러그인을 첨부한 워크스페이스는 같은 디렉터리에 두 번째 파일인 플러그인 신뢰 기록도 얻습니다.
고정을 요청받은 pull은 한 종류의 파일을 더 작성합니다. 카탈로그 디렉터리에서 아티팩트 파일을 가져오거나, 전체를 작성한 원격 source:를 가리키거나, 옆에 있는 source:를 읽는 각 Recipe와 FeatureRecipe 옆에는 해당 콘텐츠의 다이제스트를 기록하는 entity.lock이 있습니다. 이를 기록하는 것은 엔터티 작성자의 단계인 aggrega pin이며, 기본적으로 pull은 이를 수행하지 않습니다. pull은 각 엔터티의 lock이 그 단계가 기록할 내용과 일치하는지 확인하고, 고정이 없으면 중단합니다. aggrega pull --pin-sources 또는 pin_sources_at_pull: true를 설정한 워크스페이스는 대신 그 단계를 실행합니다. 이 경우 pull의 영향은 Release가 있는 디렉터리를 넘어서까지 미치지만, 작성한 엔터티 파일에는 절대 쓰지 않습니다. 이 파일은 엔터티 lock에서 설명하며, pull이 작성할 내용 미리 보기에서는 아무것도 변경되기 전에 워크스페이스의 전체 파일 집합을 보여 줍니다.
참조가 아무것으로도 해석되지 않아 거부된 pull은 어디에서 실행되든 로컬 엔터티를 읽는 위치를 알려 줍니다. 거부에는 워크스페이스가 로컬 엔터티를 읽은 디렉터리와 엔터티를 읽게 하려면 무엇을 변경해야 하는지에 대한 워크스페이스 자체의 설명이 포함되며, 이는 로컬 엔터티를 읽는 위치 안내에 나와 있습니다. 이 설명은 이 명령에서든, 의존성을 먼저 해석하는 빌드에서든, aggrega mcp의 pull 도구에서든, 편집기의 의존성 해석에서든 똑같이 포함됩니다. 이들 모두가 실행하는 해석이 이를 구성하기 때문입니다. 터미널이 거부의 첫머리에 짧은 코드를 출력하는 것처럼, pull 도구의 거부도 해당 조건의 짧은 코드와 설명 코드를 밝힙니다. 그 디렉터리에 있으면서 Aggrega apiVersion을 선언하지만(들여쓰기 없이 apiVersion:으로 시작하고 값이 aggrega.ai/로 시작하는 줄이 있음) 로드할 수 없었던 파일, 예컨대 YAML로 구문 분석되지 않는 파일은 같은 거부 안에서 로드 시 건너뛴 카탈로그 파일 중 하나로, 파서 자체가 제시한 이유와 함께 명시됩니다. 그러한 파일이 참조가 가리키는 엔터티를 선언하는 파일일 수 있으며, 그 파일에서는 어떤 엔터티를 선언하는지 알려 줄 내용을 아무것도 읽을 수 없기 때문입니다. 다른 apiVersion을 선언하거나 아무것도 선언하지 않은 YAML 파일은 Aggrega 문서가 아니며 그곳에 명시되지 않습니다.
lockfile
lockfile은 각 의존성을 URI, 확정된 버전, 콘텐츠 다이제스트로 고정합니다. lockfile에는 카탈로그 엔티티, 스키마 및 매핑 라이브러리(각각 자신을 사용하는 Components와 Features를 가리키는 역참조를 가짐), Wasm 플러그인, 소스 아티팩트, 외부 입력(각각 URL을 키로 하며 그것을 요청한 플러그인을 가짐), 그리고 Release 파일 자체에 대한 섹션이 있습니다. 파일은 정규화된 결정적 형식으로 작성됩니다.
엔티티는 그 게시물이 담는 내용으로 기록됩니다. 엔티티 행의 다이제스트는 해당 문서와 그 옆에서 문서가 지정하는 모든 파일을 포괄합니다. 즉 Recipe 또는 FeatureRecipe의 로컬 source:, $import:가 지정하는 각 파일, 옆에 있는 entity.lock, Component 또는 Feature가 가져오는 각 스키마 파일로, aggrega push가 게시하는 것과 같은 집합입니다. 각 파일은 경로와 바이트만 기여하며 그 밖의 것은 기여하지 않습니다. 아카이브의 압축 방식, 타임스탬프, 권한 비트(실행 비트 포함)는 기여하지 않습니다. 파일을 지정하지 않는 엔티티는 그 하나의 문서로 기록됩니다. 따라서 같은 엔티티는 카탈로그 디렉터리에서 읽었든 레지스트리에서 가져왔든 같은 다이제스트를 기록하며, 한 체크아웃에서 커밋한 lockfile은 같은 커밋의 다른 체크아웃에서 umask와 관계없이, 그리고 그 체크아웃의 시스템이 실행 파일 여부를 기록하는지와 관계없이 검증됩니다. Recipe 아래에서 편집한 차트, 선언한 소스에 추가한 파일, 변경된 entity.lock은 각각 다이제스트를 바꿉니다. 실행 비트가 바뀐 스크립트와 엔티티 옆에 있지만 아무것도 지정하지 않는 메모는 바꾸지 않습니다. Release가 지정하는 Aggregate와 Manifest도 같은 방식으로 각각 하나의 문서로 기록됩니다. 라이브러리는 바이트의 다이제스트로 기록되며, 어디에서 읽든 그것이 라이브러리의 문서입니다.
Manifest가 바인딩하는 모든 Recipe와 FeatureRecipe는 어느 계층이 바인딩하든 하나의 행입니다. Manifest의 name 계층이 하나의 인스턴스나 하나의 연결(attachment)에 대해 선택한 구현은 type 계층이 한 타입의 모든 인스턴스에 대해 선택한 구현과 똑같이 획득되고 기록되며, 그 행의 referenced_from은 이를 바인딩하는 항목인 manifest.spec.mappings.components.name.<instance> 또는 manifest.spec.mappings.features.name.<attachment>를 지정합니다. 빌드는 구현을 그 행에 맞추므로, 이를 기록하지 않은 lockfile은 해당 구현과 항목을 지정하며 빌드를 중단시킵니다. 두 계층에 대해서는 플랫 URI 매핑을 참고하십시오.
연결(connection)의 attachment는 컴포넌트 자체의 attachment와 똑같이 의존성입니다. 연결의 attachment가 지정하는 Feature는 Aggregate에서 컴포넌트의 uses: 항목에 작성하든 Release의 연결 항목에 작성하든, 컴포넌트 자체에 작성한 attachment의 Feature처럼 획득되고 기록되며, 그 행의 referenced_from은 작성자가 쓴 연결 항목을 지정하고 .uses.<socket>.<alias>.features.<slot>.type으로 끝납니다. Manifest가 여기에 바인딩하는 구현도 하나의 행이며, features.type이 바인딩하든 attachment의 이름 <alias>.<slot>을 키로 하는 features.name이 바인딩하든 마찬가지입니다. 빌드는 둘 다 각자의 행에 맞춥니다. 둘 중 하나가 없는 lockfile은 참조와 그것을 요청하는 항목을 지정하며 빌드를 중단시키고, pull 이후 내용이 바뀐 Feature는 두 다이제스트를 지정하며 빌드를 중단시킵니다. attachment 자체에 대해서는 Aggregate의 연결 항목을 참고하십시오.
Component나 Feature가 확장하는 베이스는 다른 무엇이 그것을 가리키든 가리키지 않든 하나의 행입니다. pull 작업은 각 extends:를 체인의 끝까지 따라가 모든 베이스를 그 자신의 종류 아래에 기록하며, 그 행의 referenced_from은 확장하는 엔터티의 spec.extends, 즉 component(<name>:<version>).spec.extends를 가리킵니다. 빌드는 그 행에서 베이스를 읽으므로, Manifest는 래퍼 자신의 타입을 매핑하며 그 베이스를 위한 줄이 필요하지 않습니다. 어떤 카탈로그 디렉터리, 캐시, 레지스트리에도 없는 베이스는 체인이 병합되는 곳에서 보고됩니다. An extends: chain cannot be assembled (체인을 조립할 수 없음)를 참조하십시오.
Release는 이름뿐 아니라 내용으로도 기록됩니다. 소스가 어떤 차트 버전으로 확정되는지, 어떤 컴포넌트가 어떤 경계에 배치되는지 등 Release가 요청하는 모든 것은 파일 내용에서 확정되므로, release_documents는 Release와 그것이 확장하는 각 Release의 다이제스트를 기록하고, release는 그 이름을 지정합니다. pull 이후 Release를 편집하면 다음 빌드는 렌더링 전에 중단되며, 편집한 파일을 지정하고 다시 pull하라고 안내합니다. 일반 aggrega pull --release <release>는 다른 모든 고정을 유지하면서 편집을 기록합니다. 다이제스트는 파일의 바이트를 있는 그대로 포괄하므로, Aggregate와 Manifest의 경우와 똑같이 주석이나 공백 변경도 반영됩니다. Release가 parameters를 통해 가져오는 파일은 이 방식으로 기록되지 않습니다.
pull은 서명을 검사하는 모든 아티팩트에서 지원 중단 마커를 찾고, 찾은 내용을 알립니다. 마커 자체의 서명이 pull이 인정하는 서명자(아티팩트 자체의 서명자 또는 레지스트리의 trusted_deprecation_identities에 있는 ID)에 대해 검증되면 그 마커는 기록되며, 심각도 및 마커의 서명자와 함께 공지됩니다. pull이 찾았지만 인정할 수 없었던 마커(읽을 수 없거나, 서명되지 않았거나, 정책이 신뢰하지 않는 사람이 서명했거나, 검사할 수 없는 서명을 지닌 마커)는 이유와 함께 marker present but not honored로 보고되며 기록되지 않습니다. 완료할 수 없었던 조회(pull이 아티팩트의 레지스트리를 열 수 없었거나 아티팩트에 첨부된 항목의 목록이 응답하지 않은 경우)는 이유와 함께 marker lookup did not complete로 보고되며 아무것도 기록하지 않습니다. pull이 마커의 존재 여부에 대해 아무것도 알아내지 못했기 때문입니다. 레지스트리 자체의 신뢰 정책이 아티팩트의 종류에 서명을 요구하고 그 정책이 advisory가 아닌 경우, 이 두 경우 중 어느 것이든 보고되는 대신 pull을 중단시킵니다. 마커가 없는 아티팩트는 아무 줄도 출력하지 않으며, 워크스페이스나 아티팩트의 레지스트리에 대해 서명 검증이 꺼져 있으면 마커를 찾지 않습니다.
고정된 의존성 매니페스트를 커밋하듯이 <release-stem>.lock을 Release와 함께 커밋하십시오. lockfile diff는 어떤 의존성 버전과 다이제스트가 바뀌었는지 검토자에게 정확히 보여 주며, 라이브러리 다이제스트 변경은 영향을 받는 사용처를 지정합니다.
특정 pull이 수행한 내용, 즉 각 엔티티를 레지스트리에서 새로 가져왔는지(fetched-fresh), 캐시 슬롯을 재사용했는지(cache-reuse), 로컬 카탈로그에서 찾았는지(local), 컴파일러 바이너리 내부의 사본에서 제공했는지(in-binary), 외부였는지(external: Release 자체의 Aggregate 또는 Manifest로, 의존성 중 하나로 확정되지 않고 Release가 지정하는 파일이나 항목에서 읽은 것입니다. pull이 레지스트리에서 가져온 Aggregate는 대신 fetched-fresh입니다)는 --detail이 stdout으로 출력하는 일시적인 pull 이벤트 진단이며, lockfile에는 절대 기록되지 않습니다. 어떤 소스가 엔티티를 제공했는지는 pull하는 머신의 로컬 상태에 따라 달라지므로, 이를 저장하면 머신 간 lockfile의 바이트 동일성이 깨집니다. 이 진단은 이번 pull이 수행한 내용을 보고하며, 이는 나중에 복구할 수 없습니다(새로 pull한 엔티티는 다음 실행 시 캐시됨). Release 의존성의 pull 이후 확정 상태를 확인하려면 aggrega inspect를 사용하십시오.
엔터티 잠금
Recipe나 FeatureRecipe는 자신의 문서 밖에 있는 바이트에 의존할 수 있습니다. 원격 source:에서 가져온 차트나 조각, artifacts 항목(또는 Recipe의 boundary.artifacts 항목)이 $import로 가져오는 파일, 디렉터리나 옆에 있는 파일을 가리키는 source:의 파일이 그 예입니다. 이들 각각의 다이제스트는 엔터티 파일과 같은 디렉터리에 있는 entity.lock이라는 파일에 기록됩니다. 작성한 엔터티 파일에는 절대 쓰지 않으며, 파생된 내용은 그 옆에 둡니다. 엔터티 잠금 스키마에서 이 파일을 필드별로 설명합니다.
누가 작성하는가. 하나의 단계가 작성합니다. 바로 aggrega pin으로, 엔터티 작성자가 실행하며 Release가 필요 없고 잠금이 담는 모든 종류의 고정을 기록합니다. aggrega pull --pin-sources와 aggrega push --pin-sources는 작성자를 대신해 같은 단계를 실행하고 같은 바이트를 씁니다. 고정을 요청받지 않은 pull은 잠금을 전혀 쓰지 않습니다. 대신 Release가 카탈로그 디렉터리에서 빌드하는 각 Recipe와 FeatureRecipe에 대해 그 단계가 기록할 내용과 잠금이 담은 내용을 비교하고, 고정이 없거나 더 이상 입력과 일치하지 않으면 엔터티, 각 입력과 그 종류, 그리고 aggrega pin을 명시하며 중단합니다. 로컬 소스의 파일은 하나의 집합으로 고정과 대조됩니다. 그중 아무것도 기록하지 않은 잠금은 pull을 중단시키며, 고정 이후 파일이 추가, 변경 또는 제거된 경우도 마찬가지입니다. 워크스페이스 키 pin_sources_at_pull은 모든 pull의 기본값을 고정으로 만들고, --pin-sources=false는 한 번의 실행에 대해 중단 동작을 되돌립니다. 고정은 작성자의 의무이므로, 소비자의 첫 pull에서 중단이 발생했다면 엔터티 게시자가 고정하지 않은 것입니다. 소비자의 해결책은 다른 사람의 디렉터리를 직접 수정하는 것이 아니라 그 키입니다. aggrega pin에서 이를 자세히 설명합니다.
담고 있는 내용. 세 개의 목록이며, 각 행은 하나의 입력을 나타냅니다.
sourceDigests—kind,url,chart,module_subdir,version,ref에 템플릿 없이 좌표를 모두 직접 작성한 원격source:마다 한 행입니다. 행에는 소스의kind와url, 있는 경우chart또는module_subdir, 해석된 버전(git 소스의 경우ref가 가리킨 커밋), 가져온 아카이브의 콘텐츠 다이제스트가 담기며, OCI로 가져온 차트에는 매니페스트 다이제스트도 추가됩니다.artifactDigests—$import로 가져온 파일이 제공하는artifacts또는boundary.artifacts항목마다 한 행이며, 항목과 파일 바이트의 다이제스트를 나타냅니다.artifacts항목은 키로,boundary.artifacts항목은boundary/<key>로 명명되므로, 같은 키로 작성된 두 블록의 항목은 따로 고정됩니다.localSourceDigests— 디렉터리나 엔터티 옆의 파일을 가리키는source:가 엔터티 게시물에 포함시키는 파일마다 한 행이며, 엔터티 기준 파일 경로와 파일 바이트의 다이제스트를 나타냅니다. 이러한 소스에 대해서는 아무것도 가져오지 않으며, 파일은 있는 그대로 다이제스트됩니다. 템플릿으로 작성된 소스는 엔터티 디렉터리의 모든 파일을 포함하므로, 그 각각에 행이 있습니다.
담지 않는 내용:
- 좌표가 템플릿으로 채워지는 원격 소스 — 예를 들어
.infra에서 읽는version입니다. 어떤 아티팩트를 가리키는지는 엔터티를 사용하는 각 Release가 결정하므로, 해석된 각 버전은 그 Release의 잠금 파일에 고정되고 엔터티 옆에는 아무것도 기록되지 않습니다. - 엔터티 파일의 일부인 인라인
artifacts또는boundary.artifacts항목, 그리고 잠금 파일이 기록하는 라이브러리 버전으로 내용이 고정되는 ArtifactLibrary에서 가져온 항목.
고정할 것이 없는 엔터티에는 entity.lock이 생기지 않으며, 더 이상 잠금이 필요 없는 엔터티에 그 단계를 실행하면 잠금이 제거됩니다.
엔터티 옆에 커밋하십시오. 모든 Recipe와 FeatureRecipe는 같은 파일 이름을 사용하고, 파일이 있는 디렉터리가 어느 엔터티에 속하는지 알려 주므로 잠금은 그 디렉터리와 함께 이동합니다. 타임스탬프가 없고 행이 고정된 순서로 유지되므로, 변경되지 않은 입력에 대한 단계 실행은 파일을 바이트 단위로 동일하게 유지하며, 그 diff는 바뀐 소스, 가져온 파일 또는 로컬 소스의 파일을 나타냅니다. 한 디렉터리에는 잠금이 하나만 있으므로, 이 단계는 다른 엔터티가 옆에 있는 Recipe나 FeatureRecipe를 거부합니다(Aggregate, Release, Manifest를 제외한 모든 종류는 자체 디렉터리를 가집니다). 고정을 요청받은 pull도 그러한 엔터티를 아무것도 해석하기 전에 거부합니다. 디렉터리당 하나의 엔터티에서 이 규칙을 설명합니다. 고정하지 않는 pull은 엔터티 옆에 아무것도 쓰지 않으며 그 디렉터리를 판단하지 않습니다.
aggrega build는 파일을 잠금과 대조합니다. 빌드는 잠금을 읽고 세 가지를 비교합니다.
- 가져온 각 파일을 다시 다이제스트하여 해당 행과 비교합니다.
boundary.artifacts파일도artifacts파일과 똑같이 처리됩니다. 고정 후 편집된 파일은[CATALOG_ERROR E0026]으로 빌드를 중단시키며, 행이 명명한 대로의 아티팩트, 가져온 파일, 두 다이제스트를 표시합니다. - 로컬 소스의 파일을 다시 다이제스트하여 해당 행들과 하나의 집합으로 비교합니다. 이는 provider가 소스를 읽기 전에 이루어집니다. 고정 이후 편집, 추가 또는 제거된 파일은 해당 소스를 가진 컴포넌트 인스턴스 아래에서
E0305로 빌드를 중단시키며, 그러한 각 파일과 두 다이제스트를 표시합니다. 엔터티 옆에 있지만 소스가 포함하지 않는 파일은 비교하지 않습니다. 로컬 소스에 대한 행을 기록하지 않은 잠금은 비교할 것이 없으며, 이는 A local source no longer matches the pins recorded beside its Recipe (로컬 소스가 Recipe 옆에 기록된 고정과 더 이상 일치하지 않음)에서 설명합니다. - 각 소스 행을 Release의 잠금 파일이 같은 소스에 대해 기록한 다이제스트와 비교합니다. 불일치는
[FETCH_ERROR E0135]로 빌드를 중단시키며, 잠금과 두 다이제스트를 표시합니다. 두 파일은 같은 소스에 대한 두 번의 해석(고정 단계와 pull)으로 작성되므로, 두 해석이 서로 다른 바이트를 얻었거나 두 파일 중 하나가 편집되었을 때 불일치가 발생합니다. 한 버전 아래 바이트가 다르다는 것은 업스트림이 버전을 다시 게시했다는 뜻입니다.
변경 이전에 작성된 잠금 파일이 먼저 중단시키며, pull이 해당 파일을 알려 줍니다. 잠금 파일은 엔터티를 그것이 담는 내용으로 기록하고, 잠금과 이 비교들이 읽는 모든 파일이 그 일부이므로, 가져온 파일, 로컬 소스의 파일 또는 잠금 자체가 바뀌기 전에 작성된 잠금 파일을 가진 빌드(또는 aggrega pull --verify)는 세 비교가 실행되기 전에 중단됩니다. The lockfile no longer matches what the release resolves to (잠금 파일이 릴리스의 해석 결과와 더 이상 일치하지 않음)로 엔터티와 두 다이제스트를 표시합니다. 그러면 일반 aggrega pull이 해당 파일을 알려 줍니다. 잠금을 고정 단계가 기록할 내용과 대조하고 고정이 더 이상 일치하지 않는 입력을 거부하기 때문입니다. An entity reads an input the lock beside it records no pin for (엔터티가 옆의 잠금에 고정이 기록되지 않은 입력을 읽음).
잠금 파일에 엔터티 자체 내용의 기록이 없는 경우, 빌드가 마주치는 것은 세 비교입니다. Manifest가 Release가 도달하는 Component나 Feature의 이름이기도 한 참조로 지정하는 Recipe나 FeatureRecipe는 자체 항목이 없습니다. 그 참조에 대한 잠금 파일 항목은 Component나 Feature를 기록하므로 Recipe의 파일이 바뀌어도 잠금 파일에서는 아무것도 바뀌지 않으며, 빌드와 검증 pull은 바뀐 파일을 위의 코드로 보고합니다. 잠금 파일의 source_artifacts 항목이 변경된 기록이고 엔터티 옆의 잠금은 변경되지 않은 경우에도 빌드가 마주치는 것은 소스 행 비교입니다.
중단에 대응하기. 가져온 파일을 의도적으로 변경했다면 해당 엔터티에 대해 aggrega pin을 실행합니다. 이 단계가 파일의 새 다이제스트를 기록하고, 다음 빌드는 이를 받아들입니다. 의도하지 않은 변경이라면 파일을 복원합니다. 변경된 로컬 소스에도 같은 두 가지 대응이 적용됩니다. 엔터티를 다시 고정하거나, 중단이 지목한 파일을 복원합니다. 잠금 파일과 일치하지 않는 소스 행의 경우, 버전 관리에서 entity.lock을 복원하거나 엔터티에 대해 aggrega pin을 실행해 다시 작성합니다.
aggrega pull --verify도 이를 검사합니다. 검증 pull은 Release가 카탈로그 디렉터리에서 도달하는 Recipes와 FeatureRecipes 옆의 잠금에 대해 동일한 세 가지 비교를 수행하고, 빌드가 거부할 모든 고정을 같은 코드와 같은 문구로 보고하며, 하나라도 있으면 0이 아닌 코드로 종료하고, 잠금은 작성하지 않습니다.
잠금이 비교되지 않는 경우. 카탈로그 디렉터리가 아닌 레지스트리에서 해석된 Recipe 또는 FeatureRecipe에는 빌드가 읽는 잠금이 없으며, 그 소스는 Release의 lockfile만으로 검증됩니다. 또한 git ref:로 작성된 소스는 해당 ref가 해석된 커밋으로 잠금에 기록되는 반면, 빌드는 엔터티가 지정한 버전으로 소스의 고정을 찾으므로, 그 행은 빌드에서도 검증 pull에서도 비교되지 않습니다. lockfile은 여전히 커밋을 고정하며, 모든 빌드는 캐시된 아카이브를 이에 대해 검증합니다.
플러그인 신뢰 기록
워크스페이스가 연결하는 플러그인 중 일부는 렌더링 출력을 전혀 만들지 않습니다. ir-verdict 또는 render-verdict 역할의 plugins.governance 연결과 모든 plugins.linter 연결은 수락 또는 거부 판정만 반환하며, 그 바이트는 아티팩트에 하나도 도달하지 않습니다. 따라서 이들은 빌드가 바이트 단위로 재현하는 대상에 속하지 않으며, 바로 그것을 고정하는 잠금 파일은 이들을 둘 곳이 아닙니다.
대신 이들의 식별 정보는 잠금 파일 옆에 커밋되는 두 번째 파일인 plugins-trust.yaml에 기록됩니다. 이 파일은 그러한 플러그인마다 하나의 항목을 담으며, 플러그인의 식별 좌표, 선택된 버전, 확인된 아티팩트의 콘텐츠 다이제스트를 기록합니다. 여기에 pull이 해당 아티팩트에 대해 서명을 검증한 경우 그 서명이, 그리고 게시자가 아티팩트를 게시한 뒤 지원 중단한 경우 pull이 발견하고 검증한 표시가 더해집니다. 플러그인 신뢰 기록 스키마에서 이 파일을 필드별로 설명합니다.
잠금 파일을 커밋하는 것과 같은 이유로 plugins-trust.yaml도 잠금 파일과 함께 커밋하십시오. 버전 관리 밖에 보관된 기록은 아무도 검토할 수 없고 무엇과도 비교할 수 없습니다. 커밋된 기록은 각 연결이 어떤 플러그인으로 확인되었는지에 대한 하나의 공유된 진술이며, 그 diff는 변경된 식별 정보를 보여 줍니다.
이 파일은 기록할 것이 있을 때만 생성됩니다. 판정을 반환하는 플러그인을 연결하지 않는 워크스페이스는 그러한 식별 정보를 확인하지 않으므로, pull은 파일을 쓰지 않고 이에 대해 아무것도 알리지 않습니다. 이는 파일이 누락된 것이 아니라 단순히 없는 것입니다. pull이 파일을 생성하면, 생성한 파일 이름을 알리고 커밋하라고 안내합니다. 이후의 pull은 기록에 아직 없는 식별 정보를 추가하고, 이미 기록된 식별 정보는 모두 그대로 둡니다.
이 파일의 모든 변경은 알려지며, 그 밖의 것은 알려지지 않습니다. 기록을 변경하는 pull은 변경된 항목마다 한 줄을 출력하여 플러그인과 변경 종류를 알립니다. 변경 종류는 처음 기록된 식별 정보, 기존 식별 정보 대신 채택된 식별 정보(무엇이 교체되었는지 볼 수 있도록 둘 다 표시), 항목이 이미 가리키는 아티팩트에 대해 기록된 지원 중단, 항목에서 해제된 지원 중단, 항목에 기록되거나 항목에서 해제된 서명, 또는 삭제된 항목입니다. 위에서 설명한 생성 안내 줄은 이와 별개로 항목이 아니라 파일에 관한 것이므로, 첫 확인에서는 둘 다 출력됩니다. 즉 이 파일이 새로 생성되었으므로 커밋해야 한다는 것과, 이 파일이 이제 담고 있는 식별 정보가 무엇인지를 알립니다.
기록을 그대로 두는 pull은 기록에 대해 아무것도 알리지 않습니다. 따라서 이 파일에 관한 줄이 출력되면 커밋된 파일이 변경되었으며 그 diff를 읽어 볼 가치가 있다는 뜻입니다. 이는 잠금 파일의 경우보다 여기에서 더 중요합니다. 잠금 파일이 고정하는 모든 것은 빌드가 바이트 단위로 재현하는 대상에도 속하므로 그 변경은 다른 곳에서도 드러나지만, 판정 플러그인의 식별 정보는 그런 곳이 없습니다. 교체된 게이트가 기록되는 곳은 이 파일뿐입니다.
aggrega pull --dry-run은 아무것도 변경하지 않으므로 이 중 어느 것도 알리지 않습니다. 대신 pull이 쓸 내용 미리 보기에서 설명하는 대로, 쓰게 될 파일 목록에 이 기록을 포함합니다.
지원 중단은 기록에 이미 있는 항목에 추가되며, 이는 항목을 다시 쓰는 것과 같지 않습니다. 이미 신뢰하는 플러그인을 게시자가 지원 중단하면, 다음 aggrega pull이 해당 플러그인의 기존 항목에 표시를 기록합니다. 아티팩트가 변경되지 않았고 새로 채택되는 것도 없으므로 좌표, 버전, 다이제스트는 그대로입니다. 따라서 일반 pull은 deprecation 블록을 추가할 수 있으며, 식별 정보를 변경하는 것은 명시적 업그레이드뿐입니다. 표시는 항목이 이미 가리키는 아티팩트에 대해서만 기록되며, 어떤 pull도 게시가 중단된 표시를 추적하지 않습니다. 기록된 표시는 그것을 담은 항목과 함께만 사라집니다. 즉 해당 항목이 삭제될 때, 또는 명시적 업그레이드가 플러그인을 다시 확인하여 항목이 이미 기록한 바이트에서 표시를 찾지 못할 때입니다.
검증된 서명도 같은 방식으로 항목에 기록되며, 모든 pull이 이를 새로 판정합니다. pull은 실행될 때마다 이러한 각 플러그인의 서명을 해당 레지스트리의 신뢰 정책에 대해 검증하고(레지스트리가 제공하는 플러그인은 이를 고정하는 것이 없으므로 매번 버전으로 가져옵니다), 검증한 내용을 식별 정보는 건드리지 않은 채 플러그인 항목에 기록합니다. 기록되는 내용은 모드, 일치한 서명자, 캐시한 서명 번들의 다이제스트로, 잠금 파일 항목이 담는 것과 같은 signature입니다. 표시와 달리 이 판정은 항목에 있던 내용을 대체하며, pull이 서명을 검증하지 않은 경우(플러그인에 서명이 없고 서명이 요구되지 않거나, skip_signature_verification 또는 advisory 레지스트리가 플러그인을 허용한 경우) 항목에는 서명이 기록되지 않습니다. 검증한 서명 번들도 다시 캐시되며, 다이제스트와 더 이상 일치하지 않는 캐시 사본은 다시 쓰입니다. 따라서 서명을 잃은 항목, 다른 플러그인의 서명이 복사된 항목, 캐시된 서명 번들이 제거되거나 변경된 항목, 또는 삭제되었거나 서명이 기록되기 전에 작성된 기록은 다음 일반 aggrega pull로 복구됩니다. 빌드는 이러한 각 플러그인을 그 사실에 따라 검사합니다. 빌드 페이지의 플러그인 신뢰 기록을 참조하십시오.
확인된 식별 정보가 기록된 것과 다르면 pull이 중단됩니다. 기록된 항목은 버전과 다이제스트를 모두 지정하므로, 어느 쪽이 바뀌든 같은 사건입니다. 즉 실행될 플러그인이 기록을 검토했던 플러그인이 아닙니다. 진단은 플러그인, 기록에 있는 내용, 이번 확인이 보고한 내용을 두 축 모두에 대해 한꺼번에 표시하며, pull은 기록을 건드리지 않고 중단하므로 검토된 식별 정보가 비교 대상으로 남아 있습니다. 버전만 바뀐 경우(바이트가 바뀌지 않은 재게시)에도 다이제스트만 바뀐 경우(같은 버전으로 다시 푸시)와 똑같이 중단됩니다.
aggrega pull --verify도 같은 비교를 수행합니다. 이 명령은 pull이 커밋하는 파일을 하나도 쓰지 않으므로 아무것도 채택하지 않으며, 그 파일들이 오늘 pull이 확인할 내용을 여전히 기술하는지 보고합니다. 기록도 그 파일 중 하나입니다. 또한 각 항목의 서명을 pull 자체가 플러그인을 검증하여 얻는 서명과 비교하고, pull이 서명을 기록, 대체 또는 해제할 항목과, 기록에 항목이 없지만 서명이 기록되지 않았다는 이유로 빌드가 거부하는 플러그인을 두 파일 모두에서 기록된 서명을 비교합니다에서 설명하는 대로 보고합니다.
새 식별 정보를 채택하려면 이름으로 요청하십시오: aggrega pull --upgrade --release <release> <plugin>을 실행하되, 플러그인은 .aggrega-config.yaml 연결에서 지정한 이름으로 버전 접미사 없이 지정합니다. 이렇게 하면 해당 플러그인 하나만 다시 확인하여 그 항목을 다시 쓰고, 다른 고정된 의존성과 다른 기록된 식별 정보는 모두 그대로 둡니다. 지정된 대상은 이러한 연결 중 하나를 가리킬 수도 있으므로, 플러그인에 잠금 파일 고정이 없어도 동작합니다. 모든 의존성을 다시 확인하는 인수 없는 aggrega pull --upgrade는 기록된 모든 식별 정보도 다시 확인하여 다시 씁니다. 인수 없는 전체 갱신 pull을 실행하며 단일 대상을 지정할 방법이 없는 aggrega build --upgrade도 마찬가지입니다.
식별 정보를 제거할 때도 이름으로 요청하십시오. .aggrega-config.yaml에서 플러그인 연결을 해제해도 그 항목은 지워지지 않으며, 이는 의도된 것입니다. 일반 aggrega pull은 항목을 제거하지 않습니다. 기록에서 지정한 이름, 즉 아래의 중단 메시지가 출력하는 문자열인 식별 좌표로 플러그인을 지정하여 aggrega pull --upgrade --release <release> <plugin>을 실행하면, 다른 고정된 의존성과 다른 기록된 식별 정보는 모두 그대로 둔 채 해당 항목이 삭제됩니다. 인수 없는 aggrega pull --upgrade는 다른 모든 것을 다시 확인하는 같은 과정에서, 더 이상 어떤 판정 연결도 가리키지 않는 항목을 모두 삭제합니다.
마지막 항목을 제거하면 파일은 삭제되지 않고 빈 상태로 남습니다. 빈 기록은 아무것도 담고 있지 않으므로 아무것도 고정하지 않고 아무것도 중단시키지 않으며, 기록이 전혀 없는 것과 같습니다. 파일을 남겨 두면 제거가 diff에 제거로 나타납니다.
스키마를 충족하지 않는 기록은 그것을 읽는 모든 명령을 중단시킵니다. 빌드, release 범위의 lint, 그리고 pull이 해당하며, 자체적으로 기록할 것이 없는 pull도 포함됩니다. 비워진 기록과 손상된 기록은 의도적으로 다르게 취급됩니다. 비우기는 마지막 항목을 제거하는 방법이고 비워진 기록은 아무 말도 하지 않지만, 내용이 더 이상 파싱되지 않는 파일은 빈 기록이 아니라 결함입니다. 이를 빈 것으로 읽으면 파일을 잘라내는 것이 비교를 끄는 방법이 되기 때문입니다. 검토된 식별 정보를 되찾으려면 버전 관리에서 파일을 복원하십시오.
컴파일러 바이너리 내부의 사본에서 제공되는 플러그인은 기록되지 않습니다. pull은 자신이 획득한 것, 즉 레지스트리에서 가져오거나 캐시에서 읽은 것을 기록하며, 바이너리에서는 아무것도 획득되지 않습니다. 그 바이트는 그것을 담고 있는 컴파일러 버전으로 식별되므로, 기록할 자체 해석이 없습니다. 따라서 바이너리에 이미 포함된 플러그인을 연결해도 그에 대한 항목은 생성되지 않습니다. 이는 기록이 획득된 아티팩트만을 다루기 때문이며, 해석이 실패한 것이 아닙니다.
빌드, release 범위의 lint, release 범위의 검증은 워크스페이스 구성을 기록에 대조합니다. 해당 연결 중 어느 것이든 실행되기 전에 aggrega build, aggrega lint --release, aggrega validate --release는, 그리고 aggrega serve와 aggrega mcp를 통해 도달하는 동일한 작업도, 구성이 지정하는 판정 연결을 기록이 담고 있는 항목과 비교합니다. 해석된 아티팩트 다이제스트가 기록된 것과 다른 플러그인은 실행되지 않고 거부됩니다. 구성된 어떤 판정 연결로도 설명되지 않는 기록 항목은 실행을 중단시킵니다. 검토되었다가 지금은 없는 게이트는 그 게이트가 승인한 출력과 구별할 수 없는 출력을 남기며, 이것이 바로 출력을 읽는 사람이 볼 수 없는 부분이기 때문입니다. 중단 메시지는 플러그인을 지정하고 의도에 따라 달라지는 두 가지 해결책을 제시합니다. 제거가 실수였다면 플러그인을 다시 연결하고, 의도한 것이었다면 위의 명시적 upgrade를 실행하십시오. 이 메시지는 해당 upgrade를 바로 실행할 수 있는 형태로 출력합니다. 반대 방향, 즉 기록에 아직 없는 연결은 앞서 설명한 첫 발견에 해당하며 어느 비교도 이를 이유로 중단하지 않습니다. 항목이 없는 연결이 피할 수 없는 유일한 제약은 서명 요구 사항입니다. 같은 세 가지 표면은 캐시에서 읽는 각 플러그인을 로드할 때 해당 항목이 기록한 서명에 대조하며, 빌드에 대해서는 빌드 페이지에서 설명합니다. 전체 카탈로그 및 단일 엔터티 lint 범위는 기록을 참조하지 않습니다.
검증이 기록에 대조되는 이유는 빌드가 실행하는 것과 같은 검사를 실행하기 때문입니다. aggrega validate --release는 아티팩트를 쓰는 것을 제외하고 aggrega build가 도달하는 모든 검사에 도달하며, 게이트 플러그인도 포함됩니다. 이것이 “검증된다”를 “빌드된다”와 같은 의미로 만듭니다. 따라서 실행하는 플러그인의 식별 정보는 빌드의 경우와 똑같이 기록과 비교됩니다. aggrega validate의 다른 범위는 기록에 대조되지 않습니다. 전체 카탈로그, 단일 엔터티, 또는 플러그인 바이너리를 검증할 때는 워크스페이스의 플러그인 연결을 전혀 읽지 않으므로, 판정 플러그인이 실행되지 않고 기록이 대조할 대상도 없습니다.
구성을 기록에 대조하면 존재와 식별 정보가 확인되며, 그 이상은 확인되지 않습니다. 기록이 지정하는 모든 게이트가 여전히 연결되어 있고, 각 게이트가 그에 대해 기록된 아티팩트에서 실행된다는 것이 확인됩니다. 실행된 게이트가 실제로 판정을 반환했는지는 확인되지 않으며, 그중 한 경우는 어디에서도 포착되지 않습니다. function이 플러그인이 실제로 선언한 export를 지정하지만 그것이 소켓이 읽는 판정 export가 아니고, 출력이 소켓이 기대하는 형태 밖의 최상위 필드를 갖지 않는 연결(빈 객체가 가장 단순한 예)은 실행되어 거부할 근거를 아무것도 반환하지 않고 빌드를 통과시킵니다. 그 출력은 승인하는 게이트의 출력과 구별할 수 없으며, 기록에 잘못된 점이 없으므로 기록과의 어떤 비교로도 이를 알아챌 수 없습니다. 실행된 플러그인은 기록된 바로 그 플러그인이며, 단지 아무것도 실행하지 않았을 뿐입니다. 인접한 두 경우는 중단되므로 이 한계는 읽히는 것보다 넓지 않습니다. 플러그인이 선언하지 않은 export를 지정하는 function은 플러그인이 로드될 때 거부되고, 소켓의 형태가 선언하지 않은 최상위 필드를 가진 출력은 우연히 비어 있는 판정 목록으로 읽히지 않고 거부됩니다. 따라서 기록된 식별 정보만으로는 게이트가 무언가를 판단했다고 보기에 충분하지 않습니다.
기록된 다이제스트는 워크스페이스가 aggrega pull이 채우는 캐시에서 해석하는 플러그인에 적용되며, 다른 방식으로 해석하는 것에는 적용되지 않습니다. 판정 연결은 일반적으로 이 방식으로 해석됩니다. lockfile에서 아무것도 이를 고정하지 않으므로 바이트가 캐시에서 오고, 그 읽기 시점에 해석된 다이제스트가 기록된 것과 비교됩니다. 워크스페이스가 다른 방식으로 해석하는 판정 플러그인은 그 읽기에 도달하지 않으며, 기록이 아니라 실제로 해석된 방식을 규율하는 것에 의해 규율됩니다. 컴파일러 바이너리 내부 사본에서 제공되는 바이트는 그것을 담은 컴파일러 버전으로 식별되고, 카탈로그 엔터티 옆에 있는 .wasm은 자신의 카탈로그 디렉터리에 있는 파일이며, 명시적 파일 시스템 경로는 지정한 그 경로이고, lockfile 고정이 있는 플러그인은 그 고정에 의해 규율됩니다. 구성을 기록에 대조하는 나머지 절반은 그렇게 제한되지 않습니다. 기록이 담고 있는 모든 항목은 그 플러그인이 어떻게 해석되든 구성된 연결로 여전히 설명되어야 합니다. 따라서 기록은 자신이 지정하는 게이트가 무엇이 제공하든 여전히 연결되어 있음을 확인하며, 캐시에서 제공되는 게이트의 아티팩트 식별 정보를 확인합니다.
준수와 업데이트
기본적으로 aggrega pull은 기존 lockfile을 준수합니다. 이미 고정된 의존성은 고정된 정확한 버전으로 해석되고(고정된 digest에 대해 검증됨), 아직 고정되지 않은 참조만 해석되어 추가되며, Release가 더 이상 도달하지 않는 참조의 고정은 제거됩니다. 따라서 변경되지 않은 Release를 다시 pull하면 아무 일도 일어나지 않습니다. 같은 lockfile을 바이트 단위로 동일하게(generated_at 포함) 재현합니다. 새 의존성을 추가하거나, 수동 편집으로 고정이 제거된 뒤 pull하면 그 빈 부분만 해석되고 다른 모든 고정은 그대로 유지됩니다.
다시 pull할 때 캐시에서 읽는 의존성은 그것을 가져온 pull이 기록한 그대로 기록됩니다. 그 행은 버전, 콘텐츠 digest, manifest_digest(마지막 것은 캐시에서 콘텐츠 옆에 저장된 manifest에서 가져옴)를 유지하며, 그 pull이 레지스트리에서 검증한 signature와 deprecation도 함께 유지합니다. 빌드가 그 행을 받아들이는 동안에는 이 중 어느 것도 다시 조회하지 않으며, --detail은 그러한 의존성을 cache-reuse로 보고합니다. 따라서 모든 의존성이 캐시되어 있고, lockfile이 신뢰 구성이 요구하는 모든 서명을 기록하며 빌드가 받아들이는 서명만 기록하고 있다면, 다시 pull할 때 레지스트리에 도달할 수 있든 없든 같은 lockfile을 작성합니다.
다시 pull할 때는 빌드가 행을 거부할 바로 그 경우에 서명을 다시 조회하며, 그러한 행은 두 가지입니다.
- lockfile이 기록하지 않은 필수 서명. 신뢰 구성이 캐시가 제공하는 의존성에 서명을 요구하는데 lockfile 행에 서명이 기록되어 있지 않은 경우(행이 편집되었거나, 이전 pull이 채운 캐시 위에 lockfile이 새로 작성되었거나, 행을 작성한 pull 이후에 요구 사항이 추가된 경우), 다시 pull할 때는 캐시에서 그 옆에 저장된 manifest의 digest로 해당 의존성의 레지스트리에 서명을 요청합니다. 이는 가져오는 의존성에 대해 하는 것과 똑같으며, 검증된 서명을 행에 기록합니다. 그 행은 빌드가 거부하는 행이므로(No verified signature is recorded for an artifact that requires one (서명이 필요한 아티팩트에 대해 검증된 서명이 기록되어 있지 않음)), 다시 pull하는 것이 그 거부를 해소하는 방법입니다. 서명을 첨부하지 않는 레지스트리, 또는 신뢰 구성이 받아들이지 않는 서명은 의존성을 가져온 pull을 중단시키는 것과 마찬가지로 다시 pull하는 작업을 중단시킵니다. pull이 서명 없는 의존성을 받아들이게 하는 설정은 그러한 행을 그대로 두고 아무것도 묻지 않습니다. 최상위 수준의
skip_signature_verification, 레지스트리 자체 항목의 같은 스위치(작업 공간 전체 서명 정책이 요구하는 종류는 제외), 그리고advisory로 표시된 레지스트리가 그것입니다. - 빌드가 받아들이지 않는 기록된 서명. 행에 기록된 서명의 캐시된 서명 번들이 그것을 캐시한 pull 이후에 제거되거나 변경된 경우, 또는 다른 행에서 복사된
signature로서 번들은 온전하지만 다른 아티팩트에 대해 만들어진 경우, 빌드는 서명 요구 사항과 관계없이 그 행을 거부합니다(A cached signature bundle does not match the digest recorded for it (캐시된 서명 번들이 기록된 digest와 일치하지 않음), A recorded signature was made for a different artifact (기록된 서명이 다른 아티팩트에 대해 만들어짐)). 따라서 다시 pull할 때는 요구 사항과 관계없이, 가져오는 의존성이 거치는 것과 같은 검증을 통해 해당 의존성의 레지스트리에 서명을 다시 묻습니다. 검증된 것이 행의 서명을 대체하고, 그것이 가리키는 번들은 다시 캐시되며, digest와 더 이상 일치하지 않는 캐시된 사본은 다시 작성됩니다. 그래서 행과 캐시는 의존성을 가져온 pull이 남긴 것을 담게 됩니다. 신뢰 구성이 받아들이지 않는 서명은 의존성을 가져온 pull을 중단시키는 것과 마찬가지로 다시 pull하는 작업을 중단시키며, 서명이 필요한 곳에서 서명을 첨부하지 않는 레지스트리도 마찬가지입니다. 검증이 아무것도 기록하지 않는 경우(적용되는 곳의skip_signature_verification은 아무것도 묻지 않고, 서명이 필요하지 않은 곳에서 서명을 첨부하지 않는 레지스트리, 또는 아무것도 검증되지 않는advisory레지스트리) 행의 서명은 지워지며, 빌드는 같은 설정에서 이를 받아들입니다.
빌드가 받아들이는 서명이 기록된 행은 다시 묻지 않으며, 서명이 기록되지 않았고 어떤 것도 서명을 요구하지 않는 행도 마찬가지입니다.
레지스트리 없이 지정된 의존성은 작업 공간이 이제 default_registry를 지정하지 않으면 물어볼 수 없습니다. 그 행은 서명을 기록한 pull에 의해 레지스트리에 연결되었으며, 기본값이 없으면 물어볼 레지스트리가 없습니다. 그러한 행이 빌드가 받아들이지 않는 서명을 기록하고 있으면, 다시 pull하는 작업은 빌드 자체의 거부와 함께 중단되면서 행을 다시 물어볼 레지스트리가 구성되어 있지 않다고 알리고, lockfile은 그대로 둡니다. 의존성이 온 레지스트리를 default_registry로 구성하고 다시 pull하면 해결됩니다.
그 준수가 적용되는 대상은 레지스트리나 캐시가 제공하는 것입니다. 로컬 카탈로그 디렉터리가 제공하는 엔터티는 그 디렉터리에서 파일이 선언하는 버전으로 해석되며, 그 과정에서 lockfile이 그에 대해 기록한 항목은 참조되지 않습니다. lockfile은 여전히 그러한 엔터티를 기록하므로 거기서 볼 수 있습니다. 하지만 그 항목을 수동으로 편집해도 엔터티가 작성한 버전에 고정되지 않으며, 다음 조정 시 파일과 일치하도록 항목이 다시 작성됩니다. 로컬에서 제공되는 엔터티 중 Release가 해석하는 버전을 바꾸려면 lockfile이 아니라 카탈로그 파일을 편집하십시오.
고정은 장소가 아니라 바이트를 지정하므로, 더 이상 고정된 내용을 담고 있지 않은 캐시 항목은 신뢰되지 않고 건너뜁니다. 제자리에서 편집된 엔터티(같은 version 아래의 새 본문)는 콘텐츠 캐시에 그 이름과 버전으로 이전 본문을 남깁니다. 카탈로그 디렉터리가 먼저 읽히므로, 여전히 카탈로그 디렉터리가 제공하는 엔터티는 그 파일에서 고정되고 오래된 항목은 읽히지 않습니다. pull이 Release의 외부 입력을 찾기 위해 실행하는 렌더링은 빌드와 같은 방식으로, 고정된 바이트를 담은 카탈로그 디렉터리에서 각 고정을 읽으며, 건너뛴 항목을 aggrega build가 출력하는 알림으로 보고합니다. 엔터티를 제공하는 카탈로그 디렉터리가 없고 레지스트리에 도달할 수 있으면, pull은 고정된 버전을 다시 가져와 항목을 다시 작성하고, 표준 오류에 항목과 두 digest를 명시하여 그 사실을 알립니다.
reuse: cache entry for <name>:<version> held <digest the entry held>, not the pinned <pinned digest>; refreshed from the registry (pin unchanged)가져온 바이트는 고정 아래의 모든 가져오기와 마찬가지로 고정에 대해 검사되므로, 그 버전으로 다른 바이트를 제공하는 레지스트리는 아래에 설명된 대로 pull을 중단시킵니다. 고정된 바이트를 담은 소스가 없는 경우(엔터티를 제공하는 카탈로그 디렉터리가 없고, 캐시 항목이 다른 바이트를 담고 있으며, 고정된 버전을 제공하는 레지스트리가 없거나 실행이 어떤 레지스트리에도 도달하지 못한 경우), pull과 aggrega pull --verify는 E0135로 중단되며(캐시 항목의 manifest가 lockfile이 고정한 것이 아니면 E0133), 읽은 각 소스와 그것이 담고 있던 내용을 명시합니다. 실행이 어떤 레지스트리에도 도달하지 못한 경우에는 고정된 버전을 다시 가져오는 단계도 함께 명시합니다.
고정된 버전을 업데이트하려면 aggrega pull --upgrade --release <release>를 실행하십시오. 기존 고정을 버리고 모든 의존성을 조건을 만족하는 최신 버전으로 다시 해석합니다. 업데이트는 명시적인 행위이며, 기본 동작은 고정된 의존성을 절대 변경하지 않습니다. 이는 npm ci / cargo / go build의 관례(기본 동작은 잠금을 실현하고, 업데이트는 선택 사항)를 따르며, aggrega build의 자동 pull을 안전하게 만드는 것도 이것입니다. 빌드는 lockfile이 고정한 것을 정확히 해석하며, 버전을 몰래 옮기지 않습니다.
인수 없는 형태는 기록된 모든 고정을 버리므로, 무엇이든 하기 전에 확인을 요청합니다. 비대화형으로 사용하려면 --yes로 미리 응답하십시오. 표준 입력이 터미널이 아니고 --yes도 없으면, 아무도 할 수 없는 응답을 기다리지 않고 거부합니다. 대상을 지정하는 형태(aggrega pull --upgrade --release <release> <uri>)는 지정하지 않은 모든 고정을 유지하므로 아무것도 묻지 않습니다. aggrega build --upgrade는 인수 없는 형태를 실행하며 같은 조건으로 제한됩니다.
고정된 버전의 레지스트리 바이트가 lockfile에 기록된 다이제스트와 더 이상 일치하지 않으면(업스트림의 불변성 위반), pull은 변경된 바이트를 조용히 채택하지 않고 무결성 오류로 중단합니다. 의도적으로 다시 고정하려면 --upgrade를 실행하십시오.
잠금 파일을 쓰지 않고 검사하기
aggrega pull --verify --release <release>는 한 가지 질문에 답합니다. 지금 aggrega pull을 실행하면 잠금 파일이나 그 옆의 플러그인 신뢰 기록이 바뀌는가 하는 것입니다. 이 명령은 pull이 수행할 해석을 수행하고, 잠금 파일과 기록을 그 결과와 비교한 뒤, pull이 커밋하는 것이 쓰이기 전에 멈춥니다. 잠금 파일, 플러그인 신뢰 기록, 모든 entity.lock은 그대로 남습니다. 잠금 파일이 없거나 차이가 있으면 각각을 명시하며 0이 아닌 코드로 종료합니다. 지원 중단 표시는 아래에서 설명하듯 비교하지 않습니다. --upgrade, --dry-run과 함께 쓸 수 없으며, --pin-sources와도 그 플래그에 어떤 값을 주든 함께 쓸 수 없습니다. verify는 entity.lock에 빠진 고정을 기록하지도 않고 그로 인해 중단하지도 않으므로, 이 플래그는 아무것도 바꾸지 않기 때문입니다.
기록된 고정을 pull과 똑같이 따릅니다. 잠금 파일이 고정한 의존성은 고정된 버전으로 해석되고 고정된 다이제스트와 대조되며, 로컬 카탈로그 디렉터리가 제공하는 엔터티는 따르기와 갱신하기에서 설명하듯 그 디렉터리에서 해석됩니다. 따라서 다음과 같습니다.
- pull 이후 레지스트리가 더 새로운 버전을 게시한 참조는 드리프트가 아닙니다. pull은 그 고정을 유지하므로 잠금 파일은 여전히 pull이 쓸 잠금 파일이며, 새 버전을 채택하는 방법은
aggrega pull --upgrade입니다. - 고정된 버전으로 이제 다른 바이트를 제공하는 레지스트리는 그 변경을 드리프트로 보고하는 대신, pull을 중단시키는 것과 같은 무결성 오류로 verify를 중단시킵니다.
- 직접 편집한 잠금 파일 행, 편집된 Release, 로컬 카탈로그 디렉터리에서 편집된 엔터티는 각각 보고됩니다. 각각이 잠금 파일과 지금 pull이 해석하는 결과 사이의 차이이기 때문입니다.
pull과 똑같이 캐시를 읽고 채웁니다. 캐시가 고정 아래 보관하는 항목(카탈로그 엔터티 또는 플러그인의 .wasm)은 레지스트리에 묻지 않고 캐시에서 읽습니다. 이 덕분에 연결된 상태의 pull이 채운 워크스페이스에 대해 오프라인 상태에서 verify를 실행할 수 있습니다. 캐시에 없는 항목은 pull이 가져오듯 가져오고, 더 이상 고정과 일치하지 않는 항목은 pull이 다루는 것과 똑같이 다룹니다. 따라서 verify는 캐시에 내용을 추가할 수 있지만, 고정을 옮기는 일은 결코 없습니다.
두 파일 모두에서 기록된 서명을 비교합니다
pull이 아티팩트에 대해 검증한 서명은 pull이 쓰는 내용의 일부입니다. 잠금 파일 항목의 signature, 그리고 판정 역할에 연결된 플러그인에 대한 plugins-trust.yaml 항목의 서명이 그것입니다. 고정이 일치하면 verify는 기록된 모든 서명을 지금 pull이 기록할 서명과 대조하고, 기록된 서명이 없는 곳에 pull이 기록하거나, 교체하거나, 지울 서명을 각각 A recorded signature is not the one a pull would record (기록된 서명이 pull이 기록할 서명이 아님)로 보고합니다. 어느 파일에 있든 그러한 모든 항목이 같은 실행에서 명시됩니다.
어떤 잠금 파일 항목을 조회할지는 pull 자체의 선택입니다. 다시 pull하면 따르기와 갱신하기에서 설명하는 바로 그곳에서 항목의 서명을 레지스트리에 묻고, verify는 그 동일한 선택을 따릅니다.
- 두 가지는 레지스트리에 묻지 않고 보고됩니다. 레지스트리가 무엇을 답하든 pull이 다시 쓰기 때문입니다. 하나는 신뢰 구성이 서명을 요구하는데 서명을 기록하지 않은, 캐시가 제공하는 항목입니다. pull은 아티팩트의 서명을 기록하거나, 서명을 확립할 수 없으면 멈춥니다. 다른 하나는 기록된 서명이 다른 아티팩트에 대해 만들어진 항목으로, pull은 이를 해당 아티팩트 자신의 서명으로 교체합니다.
- pull이 다시 조회할 다른 모든 항목은 레지스트리에 묻습니다. pull이 그 항목을 바꿀지는 레지스트리의 답만이 알려 주기 때문입니다. 이 verify가 바이트를 가져온 항목, 그리고 캐시된 서명 번들이 제거되었거나 읽을 수 없거나 변경된 항목이 이에 해당합니다. verify는 pull이 하듯 레지스트리에 묻고, 그 답이 서명을 기록하거나 교체하거나 지우는 경우 항목을 보고합니다. verify가 검증한 서명 번들은 pull이 캐시하듯 캐시되므로, 캐시된 번들이 제거되었지만 레지스트리가 여전히 기록된 서명을 제공하는 항목은 통과하며 캐시는 복구된 상태로 남습니다.
기록된 서명을 빌드가 받아들이는 항목, 그리고 서명을 기록하지 않았고 어떤 것도 서명을 요구하지 않는 항목은 pull도 verify도 레지스트리에 묻지 않습니다.
플러그인 신뢰 기록도 같은 pull과 대조됩니다. 모든 pull은 판정 역할에 연결된 각 플러그인의 서명을 레지스트리에서 검증하며, verify도 마찬가지로 검증하여 그 검증이 서명을 기록하거나 교체하거나 지울 항목을 보고합니다. 기록에 항목이 없는 플러그인은 서명이 기록되지 않았다는 이유로 빌드가 거부하는 경우 보고됩니다. pull은 서명을 담은 항목을 쓰고, 빌드는 그때까지 플러그인을 거부하기 때문입니다. 그 밖의 경우는 처음 발견된 것으로, verify는 기록에 아직 없는 어떤 식별자도 보고하지 않듯이 이를 보고하지 않습니다. 오프라인 상태에서 verify는 이 플러그인들에 대해 레지스트리에 묻지 않으며, 그 대신 무엇을 보고하는지는 오프라인에서 설명합니다.
지원 중단 표시는 비교하지 않습니다. pull 이후 아티팩트에 붙은 표시는 레지스트리의 상태이며, 워크스페이스에서 아무것도 바뀌지 않아도 변합니다. 표시 때문에 verify가 실패한다면 건드리지 않은 파일에 대한 검사가 실패하게 됩니다. 같은 이유로 기록된 표시는 빌드를 멈추지 않고 권고만 합니다. 따라서 verify가 통과한 항목에 pull이 표시를 기록할 수 있습니다.
pull이 기록할 내용 미리 보기
aggrega pull --dry-run --release <release>는 일반 pull과 똑같이 의존성을 해석한 다음, 쓰는 대신 기록했을 내용을 출력합니다. 각 파일의 경로를 밝히는 헤더 하나와 그 뒤에 해당 파일이 담게 될 내용이 이어집니다.
aggrega pull --dry-run --release release.yamllockfile만이 아니라 모든 파일을 밝힙니다. lockfile, --pin-sources에서 기록된 핀이 바뀌게 될 각 Recipe와 FeatureRecipe 옆의 entity.lock, 그리고 플러그인 신뢰 기록이 모두 같은 보고서에 나타납니다. lockfile만 보여 주는 미리 보기는 lockfile만 바뀐다고 잘못 알려 주기 때문입니다. 같은 이유로, 고정되지 않은 엔터티에서 중단될 pull은 --dry-run에서도 중단됩니다. 미리 보기가 보여 주는 것은 pull이 할 일 그대로입니다. pull이 바이트 단위로 그대로 둘 파일은 전혀 나타나지 않습니다. 보고서에 이름이 있으면 그 파일이 곧 바뀐다는 뜻입니다. 마지막 줄은 그 파일 수를 세며, pull이 바꾸지 않을 워크스페이스는 0을 보고합니다.
디스크의 어떤 것도 바뀌지 않습니다. lockfile은 쓰이거나 생성되지 않고, 엔터티 잠금은 쓰이거나 제거되지 않으며, 신뢰 기록은 생성되거나 수정되지 않습니다. 하나의 기능을 둘 이상의 provider 플러그인이 제공하고 그중 무엇도 선택되지 않은 경우, 실행은 선택을 구성에 써 넣겠다고 제안하는 대신 무엇을 지정해야 하는지 밝히며 중단합니다. 미리 보기는 지나가는 길에 구성 파일을 편집하지 않습니다.
해석 자체는 여전히 실행되므로 캐시는 여전히 채워집니다. Release가 어떤 외부 입력을 소비하는지는 그것을 렌더링한 결과이며, 해석을 거부한 실행은 보고할 것이 없으므로 --dry-run은 pull과 똑같이 가져오고 저장합니다. .aggrega/cache 아래의 내용은 lockfile이 기록한 핀을 통해서만 읽히므로, 이를 채워도 빌드가 해석하는 것은 아무것도 바뀌지 않습니다. dry run이 보여 주는 것은 pull이 기록할 내용입니다.
이 플래그와 함께 쓰면 단독 --upgrade는 아무것도 묻지 않습니다. 확인 절차가 있는 이유는 전체 갱신이 기록된 모든 핀을 버리기 때문인데, 미리 보기는 아무것도 버리지 않습니다. 따라서 갱신으로 무엇을 잃게 될지 알고 싶을 때는 aggrega pull --dry-run --upgrade --release <release> 형식을 사용하면 되며, 이는 응답 없이 실행됩니다.
--verify와 함께 사용할 수 없습니다. 그 플래그는 이미 이 파일들 중 어느 것도 쓰지 않습니다. 두 플래그를 함께 지정하면 이 플래그는 아무 일도 하지 않으면서 무언가를 한 것처럼 읽히므로, 무시하지 않고 거부합니다.
고정하는 미리 보기가 항상 완전히 보여 줄 수는 없는 것이 하나 있으며, 그런 경우 그렇다고 알려 줍니다. 고정을 요청받은 pull은 각 Recipe와 FeatureRecipe 옆의 entity.lock을 다시 쓴 다음 Release를 렌더링하여 외부 입력을 찾아냅니다. 미리 보기는 그 잠금을 건드리지 않으므로, 그곳에 기록된 핀이 오래된 경우(예를 들어 고정된 이후 가져온 파일을 편집한 경우) 그 렌더링은 쓰이지 않은 잠금이 여전히 기록하고 있는 오래된 다이제스트에 맞춰 검사되어 중단됩니다. 보고서의 나머지는 모두 pull이 기록할 내용 그대로이며, 보고된 lockfile의 외부 입력 핀만 부족합니다. 실행은 완전해 보이는 lockfile을 건네는 대신 출력과 진단 양쪽에서 이를 알립니다. 워크스페이스의 첫 해석은 영향을 받지 않습니다. 아직 기록된 다이제스트가 없어 오래될 대상이 없기 때문입니다.
이 고정값들이 기술하는 구성
lockfile은 이 Release의 빌드가 소비할 것을 고정하므로, 해석은 그 빌드가 그리는 구성을 그대로 그립니다. 즉 문서를 해석하고, 워크스페이스의 연결(attachment)이 선언하는 변환을 적용하며, 그 결과를 빌드가 완성된 그래프에 대해 수행하는 검사에 통과시킵니다. 여기서 두 가지가 따라오며, 둘 다 lockfile을 읽는 첫 빌드가 아니라 lockfile을 쓰는 패스에서 나타납니다.
그 검사가 거부하는 구성은 pull을 중단시킵니다. 대상이 소켓의 selector:를 충족하지 않는 uses: 엣지, appliesTo:가 허용하지 않는 구성 요소에 연결된 Feature, 그리고 그 검사가 보고하는 다른 모든 위반은 같은 문서의 빌드가 출력하는 진단과 함께 이 명령을 멈춥니다. 또한 중단 시 첫 번째 항목만이 아니라 모든 발견 사항을 한 번의 실행에서 알려 주므로, 한 번의 패스로 고쳐야 할 전체 목록을 얻을 수 있습니다. 이는 쓰기 전에 일어나므로 <release-stem>.lock과 plugins-trust.yaml은 그대로 남으며, 빌드되지 않을 Release가 깨끗하게 해석된 것으로 기록되는 일은 없습니다. 이것이 다루지 않는 것은 판정을 반환하는 연결입니다. 여기서는 ir-verdict나 render-verdict 연결이 실행되지 않으므로, 거부 판정은 이 명령이 아니라 그것을 디스패치하는 빌드, release 범위 lint 또는 release 범위 검증을 멈춥니다.
그래프를 형성하는 역할의 연결은 그 패스 동안 실행되므로, 해석되지 않는 플러그인은 pull을 중단시킵니다. label-transform 연결은 무엇이든 노드 레이블과 매칭되기 전에 그 레이블을 결정하고, annotation-transform 연결은 Feature 연결로 확장되는 어노테이션을 주입합니다. 둘 다 그래프가 담는 내용을 바꾸므로, 그래프를 그린다는 것은 이들을 디스패치한다는 뜻이고, 이들을 디스패치한다는 것은 각 플러그인 자체의 바이트를 보유한다는 뜻입니다. 이 패스가 바이트를 얻을 수 없는 플러그인은 실행을 중단시키며, 해당 플러그인과 그것에 대해 찾을 수 없었던 것을 알려 줍니다. 이는 같은 워크스페이스의 빌드가 그것들을 얻을 수 없을 때 하는 거부와 같습니다. 디스패치되는 것은 이 패스가 방금 해석한 연결 목록이며, 이후 빌드가 재구성할 수 있도록 lockfile이 기록하는 설정과 정의 파일을 함께 지니므로, 두 패스는 같은 입력에 대해 같은 연결을 실행합니다.
파이프라인 단계가 지명하지만 아무것도 보유하지 않은 Plugin도 pull을 중단시킵니다. Recipe나 FeatureRecipe의 pipeline이 지명하는 각 Plugin은 Release의 다른 의존성과 함께 카탈로그 디렉터리, 컴파일러 바이너리 내부의 사본, 콘텐츠 캐시 또는 레지스트리에서 해석되며, 그 어느 곳에도 없는 것은 빌드도 로드할 수 없는 것입니다. 따라서 pull은 아무것도 쓰기 전에 멈추며, 해당 Plugin과 그것을 파이프라인에서 지명하는 Recipe 또는 FeatureRecipe를, 빌드가 그 단계에 도달할 때 발생시키는 조건(A plugin reference is not a Plugin entity (플러그인 참조가 Plugin 엔터티가 아님))과 함께 알려 줍니다. 이는 Manifest가 바인딩하는 모든 Recipe와 FeatureRecipe에 적용되며, 이 Release에서 아무것도 연결하지 않는 것도 포함됩니다. 각각은 렌더링 여부와 관계없이 해석되고 고정되기 때문입니다. Plugin을 게시하거나, 빌드된 .wasm과 함께 카탈로그 디렉터리에 두고 다시 pull하십시오.
그 중단과 저하된 실행은 의도적으로 서로 다른 결과입니다. 완료할 수 없는 렌더링, 즉 해석이 외부 입력을 찾는 방법과 오프라인이 모두 설명하는 경우는 모든 의존성 고정값을 올바르게 남기므로, 고정값이 쓰이고 부족분이 보고됩니다. 검사가 거부하는 구성은 해석된 것의 부족분이 아닙니다. 그것은 빌드되지 않을 Release이므로, 그에 대해서는 아무것도 고정되지 않고 실행이 멈춥니다.
캐시
가져온 콘텐츠는 .aggrega/cache 아래에 저장되며, 카탈로그 엔터티용 entities/ 하위 트리, 소스 아티팩트용 source-artifacts/ 하위 트리, 렌더링이 소비하는 외부 입력용 inputs/ 하위 트리로 나뉩니다. 카탈로그 엔터티의 슬롯은 종류, 좌표, 버전으로(따라서 좌표와 버전을 공유하는 Component와 Recipe는 두 개의 슬롯을 유지합니다), 소스 아티팩트의 슬롯은 가져온 위치, 버전, 콘텐츠 다이제스트의 접두사로, 외부 입력의 슬롯은 콘텐츠 다이제스트로 이름이 정해집니다. 빌드가 이들 중 어디에서 읽든 그 내용은 lockfile에 기록된 내용과 대조됩니다. 따라서 동일한 버전 고정은 여러 Releases에 걸쳐 하나의 슬롯을 공유합니다. 각 소스 아티팩트 슬롯에는 기준이 되는 아카이브, 재생성된 압축 해제본, 작은 메타데이터 파일이 들어 있습니다. 압축 해제본은 읽을 때마다 재생성되므로, 빌드 출력은 압축 해제된 파일의 상태가 아니라 아카이브와 lockfile에 따라 결정됩니다.
캐시가 값에서 파생하는 모든 이름은 Windows, Linux, macOS 모두에서 허용되는 이름입니다. 좌표, 버전, 레지스트리 호스트, 다이제스트에는 파일 이름에 쓸 수 없는 문자가 들어 있습니다. 좌표의 각 부분 사이의 /, 버전 앞과 sha256: 안, 레지스트리 포트 앞의 :가 그렇습니다. 그래서 각 값(종류, 좌표, 버전, 레지스트리 호스트, 다이제스트)은 디렉터리나 파일 이름이 되기 전에 변환됩니다. 소문자, 숫자, ., _, -는 그대로 쓰고, 그 밖의 모든 문자는 +로 시작하는 이스케이프로 씁니다. 버전 1.0.0의 Component core/devtool/adminer:1.0.0은 슬롯 entities/+zx000043omponent/core+zsdevtool+zsadminer+zx00003a1.0.0/1.0.0/이 되고, 콘텐츠 다이제스트로 이름이 정해지는 슬롯은 sha256+zx00003a<hex>가 됩니다. 대문자도 이스케이프되므로, 대소문자만 다른 두 좌표는 대소문자를 구분하지 않는 파일 시스템에서도 두 개의 슬롯을 유지합니다. con처럼 Windows가 장치용으로 예약한 이름은 첫 글자가 이스케이프되며, 마침표로 끝나는 이름은 없습니다. 서로 다른 두 값이 같은 이름을 공유하는 일은 없으며, 하나의 값은 모든 머신에서 같은 이름을 가집니다. aggrega cache status는 각 항목을 변환된 이름이 아니라 그 이름의 원래 값으로 나열합니다. 카탈로그 엔터티라면 좌표, 버전, 종류로 나열합니다.
아카이브의 항목은 게시자가 붙인 이름을 유지하므로, Windows에서는 Windows가 담을 수 없는 이름의 항목이 거부됩니다. 소스 아티팩트나 카탈로그 엔터티의 아카이브에 담긴 파일은 캐시가 변환한 이름이 아니라 아카이브가 지정한 이름으로 배치됩니다. 압축 해제가 Windows에서 실행될 때, Windows가 그대로는 담을 수 없는 부분을 가진 항목, 즉 대소문자와 확장자 유무에 관계없이 NUL이나 aux처럼 장치용으로 예약된 이름이나 마침표 또는 공백으로 끝나는 부분을 가진 항목은 E0340과 함께 해당 항목을 명시하며 거부되고, 그 아카이브의 어떤 것도 배치되지 않습니다. Linux와 macOS에서는 그러한 항목이 이름 그대로 배치됩니다. 압축 해제 디렉터리 밖으로 벗어나는 항목은 모든 머신에서 거부됩니다.
카탈로그 엔터티의 슬롯은 매니페스트가 함께 있을 때만 항목이 됩니다. 슬롯에는 레지스트리가 제공한 콘텐츠와 그 옆에 해당 콘텐츠를 설명하는 매니페스트가 들어 있습니다. 콘텐츠만 있는 슬롯, 즉 두 번의 쓰기 사이에서 중단된 가져오기나 수동으로 배치된 파일은 항목이 아닙니다. pull과 검증 pull은 엔터티의 레지스트리에 연결할 수 있으면 해당 엔터티를 다시 요청하고, 아무것도 가져오지 않는 빌드는 레지스트리에 연결할 수 없을 때의 pull과 마찬가지로 해당 엔터티를 없는 것으로 취급합니다.
캐시에 들어가는 내용은 두 가지를 지켜야 합니다. 엔터티 자체의 스키마가 설명하는 형태, 그리고 캐시가 그에 대해 지정하는 위치입니다. 레지스트리에서 가져온 본문은 캐시되기 전에 해당 종류의 스키마, 즉 다시 읽을 때와 같은 검사를 거칩니다. 따라서 레지스트리가 제공하는 게시된 엔터티나 라이브러리가 자체 스키마에 의해 거부되면, 캐시되었다가 나중에 오류로 드러나는 대신 가져온 대상을 명시하며 pull이 중단됩니다. 또한 캐시 위치를 구성하는 값이 그 값이 가리키는 곳이 아닌 다른 곳에 캐시 파일을 두게 되는 경우, 즉 버전이 아니라 경로인 버전이나 자신의 위치보다 위로 올라가는 소스 url 경로 또는 module_subdir는 위치가 구성되는 시점에 문제의 값을 명시하며 거부됩니다. 직접 작성한 Recipe나 FeatureRecipe에 쓴 값도 그 값으로 캐시 위치가 구성되는 시점에 같은 방식으로 검사되며, git 소스의 module_subdir는 아래에 설명하듯이 그보다 앞서 저장소를 가져오기 전에 검사됩니다.
git 저장소는 자체 체크아웃에서 아카이브됩니다. git-repository 소스의 경우 pull은 고정된 커밋으로 저장소를 체크아웃하고 module_subdir가 지정하는 디렉터리 또는 저장소 전체를 아카이브합니다. 작성된 그대로 저장소 위로 올라가는 module_subdir, 즉 ../shared나 ..\shared는 저장소를 가져오기 전에 값을 인용하는 E0307과 함께 거부되므로, 체크아웃 밖의 어떤 것도 읽히지 않습니다. 저장소가 커밋한 심볼릭 링크는 가리키는 대상이 저장소 안에 있으면 그 파일이나 디렉터리로 아카이브되며, module_subdir 자체가 그러한 링크일 수도 있습니다. 저장소 밖으로 이어지는 링크는 링크와 그 대상을 명시하는 E0321로 pull을 중단시키고 아무것도 캐시되지 않으므로, pull하는 저장소가 사용자 머신의 파일을 pull을 통해 아티팩트로 복사하게 만들 수 없습니다. 체크아웃은 pull이 멈추면 제거되므로, 메시지는 더 이상 존재하지 않는 디렉터리가 아니라 저장소 안에서의 링크 위치와 소스가 지정한 저장소 및 리비전으로 링크를 명시합니다. 링크를 변경하는 것은 저장소 측의 몫입니다. 작업 공간 경계에서 이 동작이 적용하는 규칙을 설명합니다.
캐시는 명령을 실행한 디렉터리가 아니라 작업 공간에 고정되므로, 하나의 작업 공간에는 하나의 캐시가 있고 하위 디렉터리에서 실행한 pull은 루트에서 실행한 빌드가 읽는 것과 같은 저장소를 채웁니다.
작업 공간을 찾지 못했고 지정되지도 않은 상태의 pull은 아무것도 가져오기 전에 거부됩니다. 루트를 지정한 것이 없고 탐색으로도 아무것도 고정되지 않으면(명령을 실행한 폴더에서, 또는 절대 경로로 지정된 Release라면 그 Release의 폴더에서), 그 폴더가 루트가 되며 그 아래에 캐시를 쓰면 해당 폴더가 작업 공간이 되어 버립니다. 그래서 pull은 중단되고, lockfile과 캐시를 쓰지 않으며, 해당 폴더와 두 가지 해결 방법을 알려 줍니다. --workspace-root 또는 AGGREGA_WORKSPACE_ROOT로 작업 공간을 지정하거나, 그 폴더에 workspace: 블록을 담은 .aggrega-config.yaml을 두십시오. 루트 없이 시작된 서버에서 workspace_root 없이 호출된 aggrega mcp의 pull 도구도 같은 방식으로 거부됩니다. 이 동작이 적용되는 다른 명령은 구성에 나열되어 있습니다.
네트워크에 연결할 수 없는 곳에서 빌드하기
이 명령은 외부에 연결하는 유일한 단계이므로, 연결된 상태에서 한 번 실행하면 이후의 모든 빌드를 로컬에서 수행할 수 있습니다. 그 실행이 lockfile을 작성하고 해당 고정값이 가리키는 바이트로 워크스페이스 캐시를 채우며, 이후 빌드에는 그 밖의 어떤 것도 필요하지 않습니다.
연결되지 않은 머신으로 옮겨야 하는 것은 세 가지입니다.
- Release와 그 lockfile. Release 옆에
<release-stem>.lock을 커밋합니다. 이 파일은 각 의존성이 어떤 버전과 다이제스트로 해석되었는지를 빌드에 알려 줍니다. - 워크스페이스가 판정을 반환하는 플러그인을 연결하는 경우의
plugins-trust.yaml. 빌드는 구성이 지정하는 판정 연결을 실행하기 전에 모두 이 기록과 대조하므로, 이 기록을 함께 옮겨야 연결되지 않은 빌드가 검토된 식별 정보와 pull이 그에 대해 검증한 서명을 따르게 됩니다. 플러그인 신뢰 기록에서 설명하는 대로 lockfile 옆에 커밋합니다. - 캐시 디렉터리. 엔터티, 소스 아티팩트, 고정된 입력이 모두 이 아래에 있으며, 로컬
catalog_dirs디렉터리가 제공하지 않는 것은 모두 여기에서 읽습니다.
연결되지 않은 머신에서는 평소처럼 빌드합니다. 채워진 lockfile에 대한 빌드는 그 클로저를 캐시에서 읽지만, 그곳에서 오프라인 모드를 설정해 두는 것이 좋습니다. 그러면 네트워크에 연결하려는 시도가 먼저 시간 초과를 기다려야 하는 연결 시도 대신, 해당 모드를 명시하는 즉각적인 거부로 바뀝니다. 캐시에 없는 것과 lockfile이 고정하지 않은 외부 입력은 모두 누락된 항목과 이를 고정할 해석 방법을 명시하며 빌드를 중단시킵니다. 빈틈을 채우기 위해 몰래 가져오는 것은 없습니다.
에어갭 머신과 오프라인 워크스페이스는 서로 다른 주장이며, 그 차이를 구분해 두는 것이 좋습니다. 에어갭 뒤의 머신은 레지스트리의 로컬 사본이나 필요한 모든 것을 담은 catalog_dirs 카탈로그를 가지고 있을 수 있으며, 이 경우 그 머신에서 일반 pull은 외부에 전혀 연결하지 않고도 충족될 수 있습니다. 오프라인 모드는 명령이 무엇에 연결할 수 있는지를 나타내며, 머신이 무엇을 가지고 있는지를 나타내지 않습니다. 이 모드가 무엇을 거부하고 무엇을 그대로 두는지는 오프라인에서 설명합니다.
오프라인
오프라인 모드에서는 — 구성 파일의 최상위 offline 키, 환경의 AGGREGA_OFFLINE, 또는 명령줄의 --offline — aggrega pull이 네트워크 접근을 거부합니다. 거부는 가져오기 도중의 타임아웃이 아니라 어떤 연결도 시도하기 전에 일어나므로, 오프라인 pull은 어떤 레지스트리나 원격 소스에도 접근하지 않습니다. 커밋된 파일이나 내보낸 변수가 이 모드를 설정했고 한 명령에 대해서만 이를 해제하려면, --offline=false로 해당 실행에 한해 네트워크를 허용합니다.
--upgrade는 이 모드에서 즉시 거부되며, 여기서 그런 옵션은 이것 하나뿐입니다. 전체 갱신은 모든 의존성을 레지스트리가 현재 제공하는 가장 높은 버전으로 올리므로, 레지스트리에 현재 무엇을 제공하는지 물어야 합니다. 일반 pull은 그렇지 않습니다. 이미 기록된 고정을 따르고 고정이 없는 것만 해석하므로, 머신이 가진 것만으로 충족될 수 있습니다. 거부 메시지는 세 곳 중 어디에서 모드가 설정되었는지와 한 번의 실행에 대해 네트워크를 허용하는 방법을 알려 줍니다.
그러면 해석은 머신이 이미 가진 것, 즉 catalog_dirs 검색 스택과 .aggrega/cache 아래의 캐시만 사용합니다. 모든 참조를 충족하는 카탈로그와 캐시에 대해서는 오프라인 pull이 정상적으로 완료되고 일반 lockfile을 작성합니다. lockfile은 각 의존성의 URI, 해석된 버전과 다이제스트를 기록하며, 그 바이트를 어느 곳에서 제공했는지는 기록하지 않습니다. 따라서 같은 버전을 해석하는 오프라인 pull과 온라인 pull은 같은 lockfile을 작성합니다.
오프라인 pull이 로컬에서 충족할 수 없는 의존성은 pull을 중단시킵니다. 해당 항목은 결코 건너뛰지 않습니다.
- 어디에서도 해석되지 않는 카탈로그 엔터티는 참조와 그 참조가 있던 위치를 명시하며 pull을 중단시키므로, 누락된 의존성과 그것을 요청한 대상이 모두 명시됩니다.
- 원격
source:는 해당 소스를 명시하고 네트워크 접근을 허용하거나 연결된 환경에서 캐시를 채우라고 안내하며 pull을 중단시킵니다. - 캐시에 있지만 필요한 서명을 lockfile이 기록하지 않았거나, 기록된 서명을 빌드가 받아들이지 않는 의존성은 해당 의존성을 명시하며 오프라인 거부로 pull을 중단시킵니다. 존중과 갱신에서 설명하듯이 서명을 기록하려면 해당 레지스트리에 물어야 하기 때문입니다. 그 한 번의 실행에 네트워크를 허용하면 서명이 기록됩니다. 빌드가 받아들이는 기록된 서명은 다시 조회하지 않으므로 오프라인 pull을 멈추지 않습니다.
외부 입력은 중단시키지 않는 유일한 경우이며, 대신 그 사실을 알립니다. 외부 입력을 찾는 렌더링은 아직 저장되지 않은 것을 가져올 수 없으므로, 고정되지 않은 외부 입력이 있는 Release에 대한 오프라인 pull은 완료되어 해석한 모든 의존성 고정을 작성하고 세 가지를 보고합니다. 렌더링이 끝나지 않았다는 것, 무엇을 고정했는지, 그리고 이 Release의 빌드가 해당 URL을 명시하며 중단될 것이라는 점입니다. 작성된 의존성 고정은 올바르므로 — 렌더링에 의존한 부분이 없으므로 — 독자가 다시 만들도록 버리지 않고 유지합니다.
이는 빈틈이 아니라 의도된 동작이며, 이를 바꾸는 스위치는 없습니다. 올바른 작업을 버리는 pull은 성공한 부분을 잃게 만들고, 아무 말도 하지 않는 pull은 완전해 보이지만 그렇지 않은 lockfile을 건네게 됩니다. 그 사실을 알리는 것만이 조치할 수 있게 해 주는 유일한 결과입니다. 연결된 환경이나 캐시에 이미 해당 내용이 있는 환경에서 pull을 다시 실행하면 같은 명령이 그것을 고정합니다.
따라서 오프라인 pull은 문서가 명시하는 모든 것에 대해 축소된 결과를 내는 것이 아니라 네트워크에 접근하기를 거부하는 것이며, 외부 입력에 대해서는 도달하지 못한 것을 알려 주는 완료된 해석입니다. 존재하는 lockfile은 의존성 해석이 완료된 lockfile입니다. 그 외부 입력이 완전한지는 pull 자체의 출력이 알려 주며, 빌드는 그 기준을 적용합니다.
오프라인 모드에서 --verify는 더 적은 범위를 다루며, 그렇다는 사실을 보고합니다. 기록된 소스 ref가 현재 어디를 가리키는지 확인하려면 원격에 접근해야 하는데, 오프라인 모드는 이를 거부합니다. 그래서 오프라인 --verify는 고정된 의존성을 검사하고 그 축은 건너뛰며, 확인하지 않은 일치를 보고하는 대신 그렇다는 줄을 출력합니다. 레지스트리만 확인할 수 있는 기록된 서명 — 캐시된 서명 번들이 제거되거나 변경된 lockfile 항목의 서명 — 도 같은 방식으로 건너뛰며, 그런 항목마다 이름을 밝히는 줄을 출력합니다.
verify: offline, so the signature the lockfile records for "<reference>" was not checked at its registry, which alone can say whether a pull would record it again; this verify does not cover it레지스트리가 무엇을 응답하든 pull이 다시 쓸 기록된 서명은, 그것을 알기 위해 응답이 필요하지 않으므로 오프라인에서도 여전히 보고됩니다. 두 파일 모두에서 기록된 서명을 비교합니다에서 설명하는 대로입니다.
레지스트리가 제공하는 판정 역할에 연결된 플러그인은 오프라인 verify와 오프라인 pull이 갈리는 지점입니다. 그런 플러그인은 lockfile에 고정되지 않으므로 모든 pull이 레지스트리에서 그 .wasm을 해석하며, 그런 플러그인을 연결한 워크스페이스에 대한 오프라인 pull은 그 지점에서 멈추고 .wasm을 해석할 수 없었던 플러그인으로 그 이름을 밝힙니다. 콘텐츠 캐시에 있더라도, 그리고 그 레지스트리가 advisory로 표시되었거나 서명 검증을 건너뛰는지와 관계없이 그렇습니다. 반면 오프라인 verify는 플러그인에 대해 레지스트리에 아무것도 묻지 않습니다. 빌드가 읽는 것처럼 콘텐츠 캐시에서 플러그인을 읽고, 캐시에 그 .wasm이 없거나 게시된 매니페스트가 명시하는 다이제스트와 더 이상 일치하지 않는 것이 있으면 멈춥니다. 또한 플러그인의 신원을 플러그인 신뢰 기록과 대조하고 그 .wasm에 대해 호스트 함수를 다시 검사하며, 둘 중 하나라도 불일치하면 연결된 verify와 똑같이 중단합니다. 레지스트리가 무엇을 응답하든 pull이 항목을 다시 쓰는 경우, 즉 빌드가 항목 때문에 플러그인을 거부하는 경우에 그 플러그인을 보고합니다. 서명을 기록하지 않아서 — 항목에 서명이 없거나 기록에 해당 항목이 없어서 — 이거나, 항목에 기록된 서명이 다른 아티팩트에 대해 만들어져 pull이 플러그인 자신의 서명으로 교체하는 경우입니다. 그 밖의 모든 항목 — 빌드가 서명을 받아들이는 항목과 캐시된 서명 번들이 제거되거나 변경된 항목 — 은 서명을 검사하지 않았다는 줄로 이름을 밝히고, 그 서명에 대해서는 아무것도 보고하지 않습니다.
verify: offline, so the signature of "<plugin>" was not checked at its registry, which alone can say whether a pull would record the same signature on its entry in the plugin trust record; this verify does not cover it따라서 오프라인 verify는 연결된 pull이라면 교체하거나 지울 서명을 가진 항목 — 예컨대 서명자를 손으로 편집한 항목이나 레지스트리가 더 이상 첨부하지 않는 항목 — 을 통과시키며, 그 사실을 알리는 것은 그 줄뿐입니다. 에어갭 환경의 verify는 여전히 사용할 수 있지만, ref가 그 후 이동했는지나 건너뛴 서명이 다시 기록될지는 알려 주지 않습니다. 종료 코드만 읽는 검사는 verify가 연결된 상태로 실행될 때에만 이를 다룹니다.
aggrega build와의 통합
- 검증.
aggrega build는 해석된 모든 의존성을 lockfile과 대조하여 검증하고, 드리프트가 있으면 중단합니다. 드리프트란 내용이 더 이상 고정값과 일치하지 않는 엔터티, 라이브러리 또는 플러그인, Release가 이제 도달하지만 lockfile이 고정하지 않은 참조나 lockfile이 고정하지만 Release가 더 이상 도달하지 않는 참조, 그리고 pull 이후 편집된 Release 파일을 말합니다. 이를 해소하려면 중단 시 출력되는 명령인aggrega pull --release <release>를 실행합니다. pull은 Release를 현재 상태 그대로 해석하고, 변경된 고정값을 다시 쓰며, 나머지는 모두 유지하므로 변경하지 않은 것은 아무것도 바뀌지 않습니다. 변경된 것이 Recipe의 로컬 소스 아래 파일인 경우, 엔터티 잠금에서 설명하듯 pull은 먼저 해당 엔터티에 대해aggrega pin을 안내합니다. 이 명령이 방금 쓴 lockfile은 해당 검사를 통과합니다. 명령이 쓰기 전에 같은 검사를 실행하기 때문입니다. pull 직후 빌드가 드리프트로 중단된다면 그 빌드는 pull과 다른 입력을 받은 것입니다. 예를 들어 한쪽에만--catalog디렉터리를 전달했거나 둘 사이에 워크스페이스 구성을 편집한 경우입니다. 따라서 두 명령을 같은 입력으로 실행하십시오.aggrega validate --release와 Release를 해석하는 모든aggrega inspect선택도 lockfile에 같은 검사를 적용하고 같은 중단으로 거부하므로, 어느 쪽도 빌드가 거부하는 lockfile을 그냥 넘기지 않습니다. - 자동 pull. lockfile이 없고
auto_pull이 true이면aggrega build는 먼저 pull을 자동으로 실행합니다.auto_pull이 기본값인 false이면 빌드는 중단되고 pull을 요청합니다. 빌드가 실행하는 pull은pin_sources_at_pull을 따르므로, 고정되지 않은 엔터티에 대해서는 pull과 똑같이 중단됩니다. 빌드가 실행하는 pull 단계는 이 페이지에서 설명하는 것과 동일하므로, 기존 lockfile을 채우는 빌드는 이동된 소스 ref에 대해aggrega pull과 똑같이 중단됩니다. Determinism and integrity를 참조하십시오. - 오프라인. 오프라인 설정에서
aggrega build는 머신에 이미 있는 것만 사용하며, 연결을 시도하기 전에 네트워크 접근을 거부합니다. 캐시에 내용이 없는 참조는 가져오기 도중 실패하는 대신 빌드를 중단시키며, lockfile이 없고 채우라는 요청도 받지 않은 빌드는 온라인에서와 똑같이 lockfile을 채울 pull을 안내하며 중단됩니다.--auto-pull은 거부되지 않습니다. 이것이 요청하는 채우기는 이 페이지에서 설명하는 pull이므로, 이미 캐시되었거나 로컬 카탈로그에 있는 카탈로그 엔터티에 대해서는 레지스트리에 접근하지 않고 lockfile을 씁니다. 단, 차트를 원격 소스에서 가져오는 Recipe는 다시 해석되므로, 캐시에 해당 차트가 있더라도 오프라인에서는 중단됩니다. 그리고 어느 쪽에도 없는 참조, 또는 캐시에 있지만 필요한 서명을 lockfile이 기록하지 않았거나 기록된 서명을 빌드가 받아들이지 않는 참조는 해당 참조를 명시하는 pull 자체의 거부로 빌드를 중단시킵니다.--upgrade는 Offline에서 설명한 이유로 거부됩니다. - 카탈로그 검색. pull은
--catalog가 주어지지 않은 경우에도.aggrega-config.yaml의catalog_dirs를 따르며, 구성이workspace.releases아래에 Release 자체의 디렉터리를 지정한 경우 그것도 따릅니다. 또한aggrega build와 동일한 먼저 찾은 것이 우선하는 검색 스택을 해석하므로, pull이 고정하는 의존성은 build가 검색하는 것과 일치합니다. 나열된 디렉터리가 디렉터리가 아닌 경우(예를 들어 그곳에 아무것도 존재하지 않는 경우) 두 명령 모두 어떤 것을 해석하거나 기록하기 전에 이를 거부하며, 로컬 엔터티를 읽는 위치에서 보여주듯 해당 항목과 그것을 나열한 구성 파일 및 줄을 명시합니다.
해석이 외부 입력을 찾는 방법
이 섹션의 어떤 내용도 위의 규칙을 바꾸지 않습니다. 무언가가 고정되는 시점은 여전히 하나뿐이며, 그것은 이 명령입니다. 이 섹션이 설명하는 것은 이 명령이 세 가지 종류 중 세 번째에 도달하는 방법이며, 이는 해석을 파이프라인에 연결할 때, 성능이 저하된 실행을 읽을 때, 또는 이 명령이 애초에 렌더링을 하는 이유를 따져 볼 때 중요합니다.
카탈로그 엔티티와 소스 아티팩트는 각각 문서에 이름이 적혀 있지만, 외부 입력은 그렇지 않습니다. 앞의 두 가지를 해석하는 것은 작성한 내용을 읽는 일입니다. 외부 입력은 렌더링 도중에 provider가 이름을 지정하며, 어떤 URL을 지정하는지는 렌더링되는 값에 따라 달라집니다. values 항목이 없으면 차트 스키마의 하위 트리 전체가 컴파일되지 않고, 그 하위 트리의 모든 원격 참조가 요청되지 않습니다. Release를 읽는 것만으로는 그 집합을 열거할 수 없습니다.
따라서 이 명령은 한 번의 패스에서 두 가지 일을 합니다. 문서가 지정하는 클로저를 해석하고 고정한 다음, 그 클로저를 렌더링하여 provider가 어떤 원격 문서를 요청하는지 확인합니다. 렌더링된 아티팩트는 버려지고 고정은 유지됩니다. 둘 다 하나의 명령 내부에서 일어나며, 어느 쪽도 무언가가 고정될 수 있는 두 번째 시점이 아닙니다. lockfile 쓰기는 한 번이며, 그 쓰기가 모든 고정을 담습니다.
해석을 자동화된 파이프라인에 저렴한 단계로 연결하기 전에 알아 둘 만한 결과가 두 가지 있습니다. 렌더링을 하기 때문에 문서만 읽는 해석보다 비용이 더 듭니다. 그리고 문서만 읽는 해석에서는 일어날 수 없는 이유로 실패할 수 있습니다. 바로 이 Release를 렌더링할 수 없는 provider입니다. 그런 경우에도 의존성 고정은 기록됩니다. 그 고정의 어떤 부분도 렌더링에 의존하지 않았기 때문입니다. 진단은 중단된 단계, 고정된 내용, 그리고 빌드가 고정되지 않은 URL을 지정하며 중단될 것임을 알려 줍니다. 실행이 헛되이 되지는 않으며, 오프라인에서 같은 결과에 다른 방식으로 도달하는 경우를 보여 줍니다.
렌더링은 또한 무엇이든 쓰기 전에 lockfile을 빌드가 적용하는 비교에 맞춰 봅니다. 빌드 자체의 절차를 실행하므로, 빌드가 디스크에서 찾은 lockfile을 비교하는 것과 똑같이, 이 명령이 쓰려는 lockfile을 같은 Release의 빌드가 해석하는 결과와 비교합니다. 그 비교가 거부한 lockfile은 쓰이지 않으며, 그 이후에 명령이 썼을 다른 어떤 것도 쓰이지 않습니다. 명령은 해석과 빌드가 Release의 의존 대상에 대해 서로 다르다고 알리며 중단하고, 이어서 비교가 지목한 각 항목을 출력합니다. 사용자의 파일 중 어떤 것도 이를 일으킬 수 없고 다시 해석해도 같은 불일치에 도달하므로, 재시도하지 말고 Release와 함께 보고하십시오. 이것이 쓰기를 멈추는 유일한 렌더링 실패이며, 같은 입력에 대한 같은 Release의 빌드가 이 명령이 쓴 lockfile에 대해 드리프트를 보고하지 않는 이유입니다.
렌더링을 건너뛰는 스위치는 없습니다. 그런 스위치는 단일 시점이 없애는 바로 그 예기치 않은 상황을 선택 사항으로 남겨 두게 됩니다. 즉, Release가 깔끔하게 해석되는 동안 렌더링에 필요한 입력이 고정되지 않은 채 남아 있다가 빌드 시점에야 발견되는 상황입니다.
--auto-pull은 이와 같은 해석을 빌드에 포함하며, 빌드는 한 번만 렌더링합니다. 채우기의 렌더링이 외부 입력을 찾아 고정하는 렌더링이며, 빌드는 두 번째 렌더링을 수행하는 대신 그 렌더링을 제시합니다. 따라서 명령 하나로 하는 빌드는 채워진 lockfile에 대한 일반 빌드와 같은 렌더링 비용이 듭니다. 빌드의 렌더링 플래그 중 어떤 것이 여기에 적용되는지는 aggrega build에서 설명합니다.
이 집합은 Release의 parameters에 따라 정해지며, component 고정도 이미 그렇게 동작합니다. 해석과 빌드 사이에 Release의 parameters를 편집하는 것은 Release를 편집하는 것이므로, 어떤 렌더링이 고정되지 않은 URL을 요청하기 전에 빌드가 드리프트 비교에서 해당 파일을 지정하며 중단합니다. 해결 방법은 이 명령입니다. 별도 파일에서 가져온 parameters는 내용으로 기록되지 않으므로, 그 파일을 편집하면 렌더링까지 도달하고, 렌더링이 고정되지 않은 URL을 지정하며 중단합니다. 이때도 해결 방법으로 이 명령을 안내합니다.
결정성과 무결성
Recipe의 source:는 Release의 해석된 values와 infra(및 같은 곳에 정의된 locals)를 기준으로 버전을 템플릿으로 작성할 수 있습니다. 이 값들은 pull 시점에 해석되며 그 결과가 고정됩니다. pull은 source: 필드가 읽는 locals: 항목과 그 항목들이 다시 읽는 항목만을 Aggrega 자체 템플릿 헬퍼만으로 평가합니다. source가 읽는 항목이 Sprig 함수를 호출하면 해당 항목, 필드, 함수를 명시하며 pull이 중단되고, 어떤 source: 필드도 읽지 않는 항목은 빌드에 맡겨져 Recipe가 렌더링될 때 평가되고 검사됩니다. Resolving a source: coordinate registers a narrower function set (source 좌표를 해석할 때는 더 좁은 함수 집합이 등록됩니다)를 참조하십시오. 변경 가능한 Git 태그나 브랜치는 그것이 가리키는 구체적인 커밋으로 고정되며, 작성한 ref가 그 옆에 기록됩니다. 빌드 시점에는 캐시된 아카이브의 다이제스트가 lockfile과 대조하여 다시 검증되므로 변조된 캐시가 발견됩니다.
기록된 ref는 그것이 고정한 커밋에 묶입니다. ref를 기록하는 이유는 가독성 때문이 아니라 이후 실행에서 다시 조회하기 때문입니다. 빌드는 그 ref가 어떤 아티팩트를 가리키는지 묻고, pull은 그것이 여전히 같은 곳을 가리키는지 묻습니다. 업그레이드가 아닌 pull은 기록된 각 ref가 어디를 가리키는지 다시 조회하며, 원격에서 이동한 ref가 있으면 그 이동을 받아들이지 않고 실행을 중단합니다. 이때 아티팩트, ref, lockfile이 고정한 커밋, 현재 해석되는 커밋을 명시합니다. 이동을 받아들이려면 aggrega pull --upgrade --release <release>를 실행하십시오. 엔터티 URI를 지정하는 대상 업그레이드는 이동을 받아들이지 않습니다. source 참조는 지정할 수 있는 엔터티가 아니므로, 대상 실행은 일반 pull과 똑같이 이를 유지합니다.
이 검사는 빌드 시점의 다이제스트 재검증이 대신해 줄 수 없는 유일한 것입니다. 이동한 ref를 받아들이는 pull은 가져온 바이트와 기록된 다이제스트를 한 번에 다시 쓰므로, 빌드가 비교하는 두 값이 함께 바뀌어 일치하게 됩니다. 그 결과 lockfile을 검토할 때와 다른 소스 내용으로 빌드하게 되며, 아무것도 이를 보고하지 않습니다.
이렇게 묶이는 것은 lockfile이 기록한 ref뿐이며, ref는 작성할 때마다 기록됩니다. version:만으로 source를 지정하는 Recipe에는 ref가 없으므로 이후 실행이 다시 조회할 대상이 없습니다. 직접 작성한 버전은 모르는 사이에 바뀔 수 없으므로 이것이 올바른 동작입니다. 무엇이 기록되는지는 lockfile 레퍼런스에 설명되어 있습니다.
커밋이 아니라 ref를 작성하십시오. build는 작성한 ref를 lockfile에 기록된 ref와 대조해 git 소스 아티팩트를 찾으므로, ref: v1.2.3은 그 태그가 고정된 커밋으로 빌드되며 커밋을 Recipe에 적을 필요가 없습니다. 대신 version:에 변경 가능한 태그를 지정하는 방식은 동작하지 않으며 그런 용도로 의도된 것도 아닙니다. version:은 작성된 그대로 대조되고, git 소스의 경우 lockfile은 커밋을 고정합니다.
lockfile은 레지스트리와 원격 소스에서 가져온 내용을 고정하고, 카탈로그 디렉터리에서 해석하는 각 엔터티의 다이제스트(The lockfile에서 설명하듯 엔터티 파일과 그 옆에 지정된 모든 파일에 대한 다이제스트)와 해석 과정에서 읽은 각 Release 파일의 다이제스트를 기록합니다. ./ 또는 ../로 시작하는 source의 파일과 엔터티가 가져오는 아티팩트 파일도 The entity lock에서 설명하듯 해당 엔터티 옆의 잠금에 하나씩 고정되며, 이를 통해 변경된 파일이 무엇인지 알 수 있습니다. 빌드 사이 나머지 작업 공간의 무결성은 소스 관리 시스템이 책임집니다. 결정성 보장의 범위는 바이트 단위로 동일한 출력을 참고하십시오.
인증
레지스트리 자격 증명은 Docker 자격 증명 구성에서만 읽습니다. DOCKER_CONFIG가 지정하는 디렉터리의 config.json(그 변수가 설정되지 않았으면 ~/.docker/config.json)과, 그 파일이 credsStore 또는 credHelpers를 통해 위임하는 자격 증명 도우미나 OS 키체인입니다. aggrega login <registry>는 그곳에 자격 증명을 쓰며, docker login <registry>도 마찬가지입니다. 비공개 OCI 카탈로그나 차트 레지스트리의 경우 aggrega pull 전에 둘 중 하나를 실행하십시오. podman login과 helm registry login이 쓰는 파일은 읽지 않습니다.
읽을 수 없는 자격 증명 구성은 그 내용을 드러내지 않고 보고됩니다. config.json이 유효한 JSON이 아니거나, 항목의 auth 값이 콜론으로 연결된 사용자와 비밀번호를 base64로 인코딩한 값이 아니거나, 파일이 지정한 자격 증명 도우미가 응답할 수 없으면, 레지스트리 접근이 실패하고 메시지는 레지스트리와 자격 증명 파일을 알려 주지만 파일이나 항목의 내용은 절대 알려 주지 않습니다. aggrega login과 aggrega logout도 유효한 JSON이 아닌 config.json을 같은 방식으로 보고하며, 그 안의 어떤 것도 변경하지 않습니다. 파일을 수정하십시오. 읽을 수 없는 항목은 aggrega login <registry>로 교체할 수도 있습니다.
기존 방식의 Helm 차트 저장소나 차트 아카이브(helm-https-chart), compose 조각(compose-https-fragment), HTTP 또는 HTTPS로 접근하는 Git 저장소(git-repository)는 curl과 Git도 읽는 사용자별 자격 증명 파일인 netrc 파일로 인증합니다. 이 세 종류가 읽는 자격 증명 저장소는 이것뿐입니다. ~/.config/helm/repositories.yaml과 Git 자격 증명 도우미는 읽지 않습니다. SSH로 접근하는 Git 저장소는 SSH 에이전트를 통해 인증하며 netrc 파일을 읽지 않습니다.
machine charts.example.com login deploy-bot password <token>어떤 파일을 읽는가. NETRC 환경 변수가 설정되어 있으면 그 변수가 지정하는 파일입니다. 그렇지 않으면 홈 디렉터리의 .netrc이며, Windows에서는 %USERPROFILE%에 _netrc가 있으면 그 파일을, 없으면 그곳의 .netrc를 읽습니다. 파일이 없으면 자격 증명이 없을 뿐 오류가 아닙니다. 존재하지만 읽을 수 없거나 netrc 형식을 따르지 않는 파일은 E0360으로 명령을 중단시키고, 그 파일과 형식 오류의 경우 해당 줄을 알려 주지만 파일의 내용은 절대 보여 주지 않습니다: The netrc file cannot be read (netrc 파일을 읽을 수 없음). Linux와 macOS에서는 머신의 다른 사용자가 읽을 수 있는 netrc 파일에 대해 그 파일을 지목하는 경고가 한 번 나옵니다. 본인만 읽을 수 있게 하십시오(chmod 600).
어떤 항목이 요청에 응답하는가. 각 요청은 호스트(포트를 제외한 호스트 이름, 대소문자 무시)로 조회되며, 그 호스트를 지정하는 첫 번째 machine 항목이, 그런 항목이 없으면 default 항목이 응답합니다. 항목의 login과 password는 http와 https 모두에서 HTTP 기본 자격 증명으로 전송되며, 둘 중 하나가 없는 항목은 아무것도 보내지 않습니다. 인덱스가 차트를 다른 호스트에 두는 저장소는 요청별로 응답합니다. 인덱스 요청에는 저장소 호스트의 항목이, 차트 요청에는 차트 호스트의 항목이 사용됩니다. 자격 증명 없이 보내는 요청은 익명으로 읽을 수 있어야 하며, 401 또는 403으로 응답하는 서버는 pull을 권한 없는 가져오기로 중단시킵니다. 그 해결 방법은 추가할 항목과 그 항목을 찾은 파일을 알려 줍니다.
자격 증명은 어디에도 기록되지 않습니다. 가져오기가 실행될 때 읽혀 요청과 함께 전송됩니다. lockfile, Recipe 옆의 entity.lock, 소스 캐시, 그리고 모든 메시지는 소스의 URL을 작성한 그대로 담습니다.
소스 URL은 자격 증명을 담지 않습니다. 소스 url이 호스트 앞에 사용자를 적은 Recipe 또는 FeatureRecipe(https://user:token@charts.example.com/…, 또는 토큰만 적은 https://token@charts.example.com/…)는 문서를 읽을 때, 아무것도 가져오기 전에 E0361로 거부됩니다. Recipe 검증도 이를 거부하며, 그것에 도달하는 모든 pull, pin, 빌드도 마찬가지입니다. 메시지는 호스트를 알려 주지만 자격 증명은 절대 보여 주지 않습니다: A source URL carries a credential (소스 URL에 자격 증명이 포함됨). 대신 자격 증명을 netrc 파일의 machine 항목에 넣으십시오. SSH에서 사용자만 적은 경우(ssh://git@github.com/…)는 비밀이 아니라 계정을 가리키므로 허용되지만, 그곳에 적은 비밀번호도 마찬가지로 거부됩니다.
이 검사는 URL에서 호스트 앞부분만 읽습니다. 쿼리 문자열이나 경로에 담긴 토큰(…/index.yaml?access_token=…)은 감지되지 않으므로 그곳에 적지 마십시오. URL은 lockfile, entity.lock, 소스 캐시에 작성된 그대로 기록되며, 캐시 디렉터리의 이름도 마찬가지입니다.
환경 변수
pull이 읽는 워크스페이스 설정은 환경을 통해 재정의할 수 있으며, 이는 커밋된 구성보다 우선하고 모든 플래그보다는 후순위입니다: AGGREGA_OFFLINE(Offline 및 그보다 우선하는 플래그인 --offline 참조), AGGREGA_CATALOG_DIRS(OS 경로 목록 구분자로 구분하며, 절대 경로를 지정합니다), AGGREGA_ARTIFACT_CACHE_DIR, AGGREGA_DEFAULT_REGISTRY, AGGREGA_SKIP_SIGNATURE_VERIFICATION(눈에 띄게 동작합니다. pull이 서명을 확인했을 모든 곳에서 검증이 전역적으로 비활성화되었다는 경고를 기록합니다). 전체 목록과 우선순위 모델은 environment-variables.md를 참조하십시오.
참고 항목
- ./aggrega-build.md — lockfile을 검증하고, 구성된 경우 자동으로 pull합니다.
- ./aggrega-serve.md — 데몬은 이와 동일한 해석을
aggrega/resolveDependencies에서 제공하며,autoPull필드로 이를 요청하는 요청에 대해서는aggrega/build안에서도 제공하므로 편집기가 세션을 벗어나지 않고 실행할 수 있습니다. 어느 경우든 요청이 이를 지정할 때만 실행되며, 이 명령과 동일한 lockfile을 작성합니다. - ./aggrega-push.md — 카탈로그 엔티티를 레지스트리에 게시합니다.
- ./aggrega-lint.md —
aggrega push에 앞서는 게시 게이트입니다. - ../../architecture/13-catalog-and-registry.md — 카탈로그, lockfile, 캐시 모델 전체를 설명합니다.
개요
aggrega pull [<uri>...] [flags]설명
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.플래그
| 플래그 | 기본값 | 설명 |
|---|---|---|
--catalog | [] | 카탈로그 디렉터리이며 반복할 수 있습니다. 각 —catalog <dir>는 카탈로그 검색 스택의 앞에 추가됩니다(처음 일치하는 항목이 우선). 스택은 워크스페이스 catalog_dirs이거나, 워크스페이스 구성이 workspace.releases 아래에서 자체 디렉터리를 지정한 Release의 경우 해당 Release의 디렉터리이며, 워크스페이스 루트에 catalog라는 이름의 디렉터리가 있으면 그것으로 끝납니다. 비어 있게 작성된 catalog_dirs 목록은 로컬 카탈로그를 전혀 읽지 않습니다. |
--detail | false | 해석된 엔티티별로 이번 pull이 수행한 작업을 출력합니다. 레지스트리에서 새로 가져옴, 캐시 슬롯 재사용, 로컬 카탈로그에서 찾음, 컴파일러 바이너리 내부에서 제공, 또는 외부(Release가 지정하는 파일이나 항목에서 읽은 Release 자체의 Aggregate 또는 Manifest) 중 하나입니다. stdout에만 출력되며 lockfile에는 기록되지 않습니다 |
--dry-run | false | 의존성을 해석하고, 작성하는 대신 이번 pull이 작성할 내용을 출력합니다. 각 파일의 경로와 그 파일이 담을 내용은 stdout으로 출력되며, lockfile, —pin-sources에서 기록된 고정값이 바뀔 모든 Recipe 및 FeatureRecipe 옆의 entity.lock, 플러그인 신뢰 기록은 모두 변경되지 않습니다. 실제로 변경될 파일만 표시됩니다. 해석 자체는 평소와 똑같이 실행되므로 콘텐츠 캐시는 여전히 채워지고, 고정되지 않은 엔티티에서 중단될 pull은 여기서도 중단되며, 단독 —upgrade는 어떤 고정값도 버리지 않으므로 아무것도 묻지 않습니다. dry run이 보여 주는 것이 곧 pull이 작성할 내용입니다. 이미 그중 아무것도 작성하지 않는 —verify와 함께 사용할 수 없습니다 |
--include-prerelease | false | 아직 구현되지 않았습니다. 받아들여지지만 무시되므로, 이를 전달하는 스크립트는 이 플래그가 효과를 갖기 시작할 때에도 계속 동작합니다 |
--pin-sources | false | 고정값을 기록하지 않은 lock을 가진 엔티티에서 중단하는 대신, 이 Release가 빌드하는 Recipes 및 FeatureRecipes에 대해 엔티티 작성자의 고정 단계를 실행하여 각 엔티티 옆의 entity.lock에 그 엔티티가 읽는 모든 입력(전체가 기록된 원격 source:, artifacts 항목이 가져오는 파일, 로컬 source의 각 파일)의 고정값을 기록합니다. aggrega pin과 동일한 단계이며 동일한 바이트를 작성합니다. 엔티티 옆에 작성하므로 엔티티에 쓰기 가능한 위치, 즉 카탈로그 디렉터리 중 하나에 있는 문서인 경우에만 실행됩니다. 캐시에서 해석된 엔티티에는 그런 위치가 없으므로 고정되지 않습니다. 워크스페이스의 pin_sources_at_pull을 양방향으로 재정의합니다. 설정 값과 관계없이 —pin-sources는 이번 실행에서 고정하고 —pin-sources=false는 이번 실행에서 중단합니다 |
--progress | false | stderr가 터미널이 아닌 경우에도 pull 진행 표시를 강제로 켜서, 각 단계가 완료될 때마다 소요 시간과 함께 한 줄의 일반 텍스트를 출력합니다. 기본값은 auto입니다. 대화형 단계 체크리스트는 stderr가 이스케이프 시퀀스를 해석하는 터미널일 때만 표시되고, 이를 해석하지 않는 터미널에는 동일한 일반 텍스트 줄이 출력되며, 리디렉션되거나 파이프된 출력에는 아무것도 출력되지 않습니다 |
--quiet | false | stderr의 pull 진행 표시를 끕니다. stdout에는 영향을 주지 않습니다. —progress보다 우선합니다 |
--release | — | Release YAML 파일의 경로입니다(필수). 상대 경로는 워크스페이스 루트가 아니라 명령을 실행하는 디렉터리를 기준으로 해석됩니다. 해당 디렉터리가 어떤 워크스페이스에도 속하지 않고 루트도 지정되지 않은 경우, 절대 경로는 Release 자체의 폴더에서 워크스페이스를 찾습니다 |
--upgrade | false | 현재 레지스트리 상태에서 의존성을 다시 해석하여 각 의존성을 사용 가능한 가장 높은 버전으로 올립니다. 단독으로(위치 인수 URI 없이) 사용하면 lockfile을 버리고 모든 엔티티를 다시 해석하며, 기록된 모든 고정값을 버리므로 먼저 확인을 요청합니다. 하나 이상의 엔티티 URI와 함께 사용하면 해당 엔티티만 다시 해석하고 다른 모든 고정값과 기록된 외부 입력은 변경하지 않으며, 아무것도 묻지 않습니다(—verify와 함께 사용할 수 없음) |
--verify | false | lockfile, 플러그인 신뢰 기록, 어떤 entity.lock도 작성하지 않고, 기존 lockfile을 지금 pull이 수행할 의존성 해석과 대조하여 검증합니다. 차이가 있거나 lockfile이 없으면 0이 아닌 코드로 종료합니다. 해석은 pull과 똑같이 lockfile이 기록한 고정값을 따릅니다. pull 이후 레지스트리가 더 새로운 버전을 게시한 참조는 pull이 그 고정값을 유지하므로 차이가 아니며, 레지스트리가 이제 고정된 버전으로 다른 바이트를 제공하면 pull을 중단하는 것과 같이 verify를 중단합니다. 콘텐츠 캐시는 pull이 읽고 채우는 것과 같이 읽히고 채워집니다. 캐시가 고정값으로 보유한 항목은 레지스트리에 묻지 않고 거기서 읽히고, 보유하지 않은 항목은 가져오며, 더 이상 고정값과 일치하지 않는 항목은 pull이 처리하는 것과 똑같이 처리됩니다. 또한 Release가 도달하는 카탈로그 디렉터리의 각 Recipe 및 FeatureRecipe 옆 entity.lock을 빌드가 비교하는 대상과 대조하고, 빌드가 거부할 고정값이 있으면 0이 아닌 코드로 종료합니다. 즉 기록된 다이제스트와 더 이상 일치하지 않는 가져온 파일, 파일들이 기록된 다이제스트와 더 이상 일치하지 않는 로컬 source, 또는 lockfile과 일치하지 않는 source 고정값입니다. 또한 lockfile이 각 아티팩트에 대해 기록한 서명과 각 플러그인에 대한 플러그인 신뢰 기록을 지금 pull이 기록할 것과 비교하고, pull이 이를 기록, 교체 또는 삭제할 경우 0이 아닌 코드로 종료합니다. 요구 사항이 요청하지만 기록되지 않은 서명과 다른 아티팩트용으로 만들어진 서명은 pull이 레지스트리의 응답과 관계없이 다시 작성하므로 레지스트리에 묻지 않고 보고됩니다. pull이 다시 조회하여 변경 없이 기록할 수도 있는 서명(아티팩트를 가져왔거나, 캐시된 서명 번들이 제거 또는 변경된 경우)은 해당 레지스트리에 조회하거나, 오프라인 상태에서는 확인하지 않은 채 그렇다는 내용의 줄을 출력합니다. 플러그인 신뢰 기록이 포함하는 각 플러그인은 모든 pull이 검증하는 것과 같이 해당 레지스트리에서 검증됩니다. 단, 오프라인 상태에서는 빌드가 읽는 것과 같이 콘텐츠 캐시에서 읽히고, 식별 정보와 호스트 함수는 여전히 확인되며, 서명은 확인하지 않은 채 그렇다는 내용의 줄을 출력합니다. 다만 서명을 기록하지 않았거나 다른 아티팩트용 서명을 기록하여 빌드가 거부하는 경우에는 이를 보고합니다. 지원 중단 표시는 비교하지 않습니다. 또한 lockfile이 기록한 컴파일러 및 코어 플러그인 버전을 보고합니다. 이는 감사용으로 보고될 뿐 이 바이너리와 비교되지 않으므로 툴체인 차이는 결코 차이로 간주되지 않습니다. 어떤 값이 주어지든 —pin-sources와 함께 사용할 수 없습니다. verify는 entity.lock에 없는 고정값을 기록하지도 않고 그로 인해 중단하지도 않으므로 이 플래그는 아무것도 바꾸지 않습니다(—upgrade와 함께 사용할 수 없음) |
--yes | false | 비대화형 사용을 위해 단독 —upgrade 확인에 미리 응답합니다. 이 플래그는 그 하나의 프롬프트에만 적용되며 다른 것에는 영향을 주지 않습니다. 다른 모든 형태의 pull은 아무것도 묻지 않으므로, 이를 전달해도 해당 경우의 동작은 바뀌지 않습니다 |