콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

Wasm 플러그인 개발자 가이드

이 문서는 Aggrega WebAssembly(Wasm) 플러그인을 작성하고 카탈로그 엔터티로 게시하는 방법을 다루는 기준 가이드입니다. 플러그인 작성자의 계약을 처음부터 끝까지 설명합니다. 플러그인이 무엇인지, 플러그인이 호스트에 자신을 어떻게 기술하는지, 익스포트와 기능 클레임을 어떻게 작성하는지, 호스트가 적용하는 런타임 제한과 호스트 함수, 플러그인을 카탈로그로 가져오는 Plugin 엔터티, Recipe 또는 FeatureRecipe가 플러그인을 참조하는 방법, 그리고 디스크의 .wasm 파일을 빌드가 사용하는 검증되고 다이제스트로 고정된 아티팩트로 만드는 게시→풀→빌드 수명 주기를 다룹니다.

함께 보는 페이지인 plugin-contract.md는 소켓, 즉 플러그인이 연결되는 파이프라인 지점과 각 소켓이 받아들이고 생성하는 입출력 형태를 설명합니다. 이 가이드는 플러그인, 즉 엔터티, 기능 표면, 수명 주기를 설명합니다. 플러그인이 대상으로 하는 소켓은 계약 페이지에서 확인하고, 플러그인을 작성하고 배포하는 방법은 이 페이지에서 확인하십시오.

레퍼런스가 아니라 전체 작업을 따라가는 실습 경로가 필요하다면, provider 작성하기에서 작은 provider 게스트 하나를 처음부터 끝까지 만들어 봅니다. 디스크립터, 빌드, 엔터티, 연결, 그리고 출력을 직접 읽을 수 있는 렌더링까지 다루며, 첫 초안이 흔히 겪는 거부와 그 거부를 읽는 방법도 포함합니다.

1. Wasm 플러그인이란

Wasm 플러그인은 지정된 소켓에서 컴파일러를 확장하는 WebAssembly 모듈입니다. Go 호스트 바이너리에는 클라우드 전용 로직이나 인프라 로직이 전혀 들어 있지 않습니다. 템플릿 렌더링, 형식 변환, 정책 평가, 린팅 등 도메인에 특화된 모든 지능은 플러그인 안에 있습니다. 호스트는 파이프라인을 조율하고 각 소켓의 페이로드를 ABI 경계 너머의 게스트에 전달하며, 게스트는 도메인 작업을 수행하고 해당 소켓의 결과 형태를 반환합니다. 모든 소켓의 페이로드와 결과는 정규 CBOR로 전달되며, 예외는 두 가지입니다. CLI 플러그인은 인수 벡터를 JSON 텍스트로 받아 종료 코드와 스트리밍하는 텍스트로 응답하고, describe 자기 보고는 JSON 텍스트입니다. 플러그인 계약의 각 소켓 절에 해당 인코딩이 명시되어 있으며, 게스트는 키트의 페이로드 타입이 이미 제공하는 진입점을 통해 이를 읽고 쓰므로 어떤 게스트도 바이트를 직접 파싱하지 않습니다.

플러그인은 AOT 순수성 방화벽 뒤에서 실행됩니다. 호스트는 내장된 Wasm 런타임을 통해 기능이 거부된 구성으로 모듈을 로드하고 실행합니다. 네트워크 소켓, 파일 시스템, 환경 변수가 없고, 표준 입출력은 폐기되며, 관찰 가능한 벽시계는 빌드와 무관하게 고정된 시점으로 동결됩니다. 게스트가 시도하는 모든 I/O 호출은 호출 경계에서 실패하므로 플러그인은 런타임 상태에 접근할 수 없습니다. 이 방화벽을 염두에 두고 플러그인을 작성하십시오. 플러그인은 전달받은 페이로드를 변환하여 호스트가 그대로 사용하는 결과를 반환하며, 결정성은 작성자의 책임입니다. 동일한 입력은 동일한 출력 바이트를 생성해야 합니다. 원격 콘텐츠를 위해 허용된 유일한 채널은 호스트가 중개하는 외부 입력 가져오기(4절)이며, 이는 게스트에게 실시간 네트워크 접근을 주는 대신 다이제스트 고정 방식으로 바이트를 제공합니다.

플러그인이 대상으로 삼을 수 있는 소켓(토폴로지 구성 시의 변경 게이트, 정적 분석 시의 검증 게이트, FeatureRecipe 파이프라인, 대역 외 린터, 프로바이더 렌더링 소켓 등)과 소켓별 입력/출력 형태는 plugin-contract.md에 설명되어 있습니다. 플러그인이 어떤 소켓을 담당하는지는 metadata.pluginType에 선언하는 하나의 값으로 정해지며, 이 필드가 허용하는 값 전체는 entities/plugin.md §“metadata.pluginType”의 참조 항목에 있습니다. 이 가이드의 예제에서는 provider(IR 노드를 프로바이더 고유 아티팩트로 렌더링), linter(작성된 콘텐츠를 검사하여 진단을 발생), pipeline-step(FeatureRecipe 또는 Recipe의 pipeline:에서 렌더링된 문서 집합을 패치하는 단계)을 사용합니다.

게스트는 Go, Rust, TypeScript의 세 가지 언어로 제공되는 플러그인 개발 키트(PDK)를 통해 호스트를 대상으로 작성합니다. PDK는 하부의 Wasm 툴체인을 감싸고, 각 소켓이 전달하는 입력 및 출력 형태에 대해 Aggrega 타입의 빌더를 제공합니다.

2. describe() 자체 보고

모든 플러그인은 플러그인의 자체 보고를 반환하는 describe() 함수를 내보냅니다. 자체 보고에는 플러그인이 구현하는 소켓 유형, 대상으로 하는 ABI 버전, 플러그인이 주장하는 기능(소켓 유형에 따라 해석되므로 provider나 파이프라인 단계에서는 기능 이름이고, 파서나 임포터에서는 접두사가 붙은 소스 형식입니다), 가져오는 호스트 함수, 그리고 제공하는 각 진입점의 내보내기별 기능이 담깁니다. describe()는 플러그인이 무엇이며 무엇을 하는지에 대한 플러그인 자신의 설명입니다.

자체 보고는 신뢰 모델의 기준점입니다. 플러그인을 카탈로그로 가져오는 Plugin 엔터티(5절)는 같은 사실을 작성된 주장으로 다시 기술하며, 호스트는 두 시점에 엔터티의 주장을 플러그인의 describe() 출력과 교차 검사합니다. 하나는 게시 시점으로 레지스트리에 어떤 바이트도 저장되기 전이고, 다른 하나는 로드 시점으로 플러그인이 실행되기 전입니다. 불일치가 있으면 명시적으로 중단됩니다. 엔터티는 사람이 읽을 수 있고 카탈로그에서 보이는 표면이며, describe()는 호스트가 엔터티를 대조하여 검증하는 기계적 기준 기록입니다. 두 가지가 일치하도록 작성하십시오. 교차 검사는 바로 둘이 서로 어긋나는 경우를 잡아내기 위해 존재합니다. 이 검사는 엔터티가 주장하는 내용을 확인할 뿐, 빠뜨린 내용은 확인하지 않습니다. 바이너리가 보고하는 것보다 적게 주장하는 엔터티(예: 익스포트를 추가한 재빌드 뒤에 그대로 남은 엔터티)는 더 이상 바이너리가 하는 일 전부를 기술하지 않더라도 여전히 로드됩니다.

3. export 작성과 capability 주장

플러그인은 하나 이상의 export를 제공합니다. export는 호스트가 디스패치하는 이름 있는 진입점입니다(예: render_node, lint_naming, step). 각 export는 capability 블록을 가지며, 이는 해당 export가 무엇을 하는지에 대한 작성자의 주장입니다. export의 capability에는 네 개의 필드가 있습니다.

  • name — export의 ABI 이름으로, 호스트가 디스패치하는 이름입니다. 필수입니다.
  • operates — export가 수행하는 파이프라인 작업으로, patch(기존에 렌더링된 문서를 수정) 또는 emit(새 문서를 추가)입니다. 이는 선언된 capability 주장입니다. 호스트는 게시 시점과 로드 시점에 이를 플러그인의 describe() 자기 보고와 교차 검증하므로, 엔티티에 작성된 주장과 플러그인 자신의 설명이 일치해야 합니다. 이는 export에 대한 검증되는 주장이며 디스패치 스위치가 아닙니다. 렌더링 시점에 단계가 실제로 수행하는 작업은 게스트가 반환한 결과에 담기며, 이 필드에서 선택되지 않습니다. 생략하면 작업 주장이 없습니다.
  • scope — export가 작업하는 문서 루트로, own(노드 자신의 렌더링된 문서) 또는 host(component 범위의 FeatureRecipe가 연결된 component의 문서)입니다. 파이프라인 단계의 플러그인이 실행되기 전에 호스트는 단계에 선언된 export 범위를 읽고, 해당 범위의 문서를 렌더링하는 provider가 플러그인의 spec.pipelineStep.capabilities(5절)에 포함되어 있는지 강제합니다. own 범위 export는 노드 자신의 문서를 렌더링하는 provider와, host 범위 export는 호스트 component의 provider와 대조하며, 범위가 비어 있으면 이 검사에서는 own으로 간주합니다. 이것이 단계보다 먼저 실행되는 provider 호환성 검사입니다. 게스트 작업이 실제로 다루는 문서는 게스트가 반환한 결과에서 작업별로 지정되며, 이 선언된 필드에서 선택되지 않습니다. 생략하면 기본값은 own입니다.
  • selector — export가 작용하는 대상에 대한 자유 형식의 사람이 읽을 수 있는 설명입니다(예: workloads carrying a pod template). 카탈로그 독자와 aggrega inspect 화면을 위한 문서이며, 컴파일러는 이를 해석하지 않습니다.

export는 읽히기를 원하는 순서대로 작성합니다. 항목은 엔티티와 inspect에서 작성자의 순서를 유지합니다. 작성된 export가 없는 플러그인은 export 표면을 선언하지 않으며, 이는 소켓에 export별 capability 주장이 필요하지 않은 플러그인에 유효합니다.

4. 런타임 제한과 호스트 함수

플러그인 엔터티는 호스트가 플러그인을 로드하고 실행하는 방식을 제한하는 선택적 runtime 블록을 가질 수 있습니다.

메모리 및 시간 제한. maxMemoryPages는 플러그인의 선형 메모리를 Wasm 페이지 단위(페이지당 64 KiB)로 제한하고, timeoutMs는 한 번의 호출 동안 플러그인 자체 코드가 실행될 수 있는 시간을 밀리초 단위로 제한합니다. 플러그인이 호출하는 호스트 함수 내부에서 소비된 시간은 여기에 포함되지 않습니다. Linux에서는 게스트를 실행하는 스레드의 프로세서 시간으로 측정하므로, 바쁜 머신에서 게스트가 프로세서를 기다리며 보낸 시간도 포함되지 않습니다. 다른 시스템에서는 경과 시간으로 측정합니다. 새로 로드된 플러그인에 대한 첫 호출에는 해당 호출 안에서 실행되는 게스트 언어 런타임의 일회성 초기화도 포함됩니다. 두 제한 모두 기본값이 있는 선택 항목입니다. 0이거나 없으면 플랫폼 기본 상한이 적용됩니다. 엔터티가 아무 제한도 선언하지 않으면 로더가 모든 플러그인에 플랫폼 기본 상한을 적용하므로, 로드는 절대 무제한이 되지 않으며 호출은 항상 취소할 수 있습니다. 어태치먼트가 기본값보다 실제로 더 많은 메모리나 시간을 필요로 할 때 엔터티에서 제한을 높이십시오.

호스트 함수. hostFunctions는 플러그인이 임포트하는 호스트 함수 이름을 기록합니다. 이는 기계가 도출하는 필드이므로 직접 작성하지 마십시오. aggrega plugin sync가 .wasm 임포트 섹션에서 호스트 함수를 직접 읽어 엔터티 파일에 필드를 기록해 주며, 게시 과정은 바이너리에서 이를 다시 도출하여 기록이 다른 엔터티를 거부합니다. 따라서 플러그인은 바이너리가 실제로 임포트하는 호스트 함수만 정확히 받으며, 이는 선별된 허용 목록에 대해 검증됩니다(허용 목록 밖의 임포트는 명시적으로 거부됩니다). 이 기록은 콘텐츠 주소 지정 plugin: 참조가 게시된 바이트의 스냅샷인 것과 마찬가지로 게시된 바이너리의 스냅샷입니다. 즉 게시 시점의 바이너리를 반영하며, 플러그인을 pull할 때 다시 도출되고 검증됩니다. 게시 전에 로컬 .wasm이 임포트하는 호스트 함수, 즉 aggrega plugin sync가 기록하는 값을 확인하려면 aggrega inspect --plugin <file.wasm>을 실행하십시오.

선별된 호스트 표면. 호스트 함수 중 세 개는 범용입니다. aggrega_log(레벨과 메시지를 받아 호스트의 로그 대상에 한 줄의 로그로 출력), aggrega_emit_warning(코드, 메시지, 경로를 받아 호스트가 호출 후 표시하는 구조화된 경고로 누적), aggrega_fetch_external_input(URL을 받아 아래의 고정 규율에 따라 입력의 바이트로 응답)입니다. PDK는 세 함수를 각 언어로 감쌉니다. Go: aggrega.Log, aggrega.EmitWarning, aggrega.FetchExternalInput, Rust: log, emit_warning, fetch_external_input, TypeScript: log, emitWarning, fetchExternalInput. 따라서 게스트는 원시 ABI 대신 타입이 지정된 함수를 호출합니다. 소스 및 파싱 콜백(획득한 소스의 일부를 읽거나 호스트를 통해 파싱된 트리를 얻는 게스트용)과 각 콜백의 슬롯이 담는 인코딩은 plugin-contract.md에 나열되어 있습니다.

로컬 소스 콘텐츠는 호스트를 통해 전달되며, 파일 시스템에서 오지 않습니다. 프로바이더 렌더 플러그인은 디스크에서 소스를 읽지 않습니다. 파일 시스템 호출은 호출 경계에서 실패합니다. 호스트는 렌더 페이로드 안에 소스 목록을 담아 게스트에 전달합니다. 이는 각 항목의 소스 루트 기준 상대 경로와 디렉터리 여부를 정렬된 순서로 담은 것으로, 파일 내용은 포함하지 않습니다. 게스트는 여기에 자체 레이아웃 로직을 적용한 다음, 선택한 파일만 소스 콜백을 통해 다시 읽어 들이며, 콜백은 호스트가 소스 루트 아래에서 읽은 바이트를 반환합니다. 소켓별 페이로드 형태와 콜백은 plugin-contract.md에 문서화되어 있습니다.

원격 콘텐츠는 외부 입력 가져오기를 통해 전달됩니다. 원격 콘텐츠(차트 아카이브, 원격 스키마 문서)가 필요한 플러그인은 PDK의 fetch 래퍼를 호출합니다. 와이어 상에서 게스트는 URL을 UTF-8 텍스트로 aggrega_fetch_external_input에 전달하고, 정규 CBOR로 된 응답 하나를 받습니다. 이 응답에는 가져온 원시 바이트 또는 기계가 대조할 수 있는 코드와 함께 오류 메시지가 담깁니다. 래퍼는 응답을 바이트 또는 오류로 디코딩합니다. 바이트는 유효한 UTF-8이 아닌 페이로드를 포함하여 가져온 그대로 도착하며, 길이가 0인 페이로드는 오류가 아니라 빈 바이트로 반환됩니다. 호스트는 외부 입력 고정 규율에 따라 URL을 제공합니다.

  • Release의 lockfile에 이미 고정된 URL은 로컬 콘텐츠 주소 지정 저장소에서 제공되며, 읽을 때마다 기록된 다이제스트에 대해 검증됩니다. 저장소에 없는 blob은 기록된 다이제스트로 네트워크에서 다시 채워지며, 다이제스트로 검증된 재충전은 출력을 바꿀 수 없습니다.
  • 고정되지 않은 URL은 해당 URL과 해결 방법을 명시한 오류와 함께 거부됩니다. 빌드는 lockfile이 기록한 클로저를 렌더링하므로, 어떤 빌드도 고정되지 않은 참조를 가져오지 않으며 그렇게 하도록 만드는 설정도 없습니다.
  • 고정은 Release의 의존성이 해석될 때 이루어집니다. aggrega pull은 Release를 렌더링하여 렌더가 요청하는 외부 입력을 파악하고, 각각을 가져와 의존성 고정 정보와 함께 lockfile에 기록합니다. 따라서 플러그인 작성자의 작업 흐름은 한 번 해석한 뒤 원하는 만큼 오프라인으로 빌드하는 것입니다.

허용되는 스킴은 https, 루프백 호스트에 한한 http, 그리고 oci(매니페스트 다이제스트로 고정)입니다. lockfile은 고정된 모든 입력, 즉 URL, sha256 다이제스트, 크기, 그리고 해당 입력을 요구한 플러그인을 기록하므로, 재빌드는 로컬 저장소에서 동일한 바이트를 제공합니다. 재현 가능하며, 한 번 고정되면 오프라인으로 동작합니다.

Go PDK 사용 시:

import "github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega"
chart, err := aggrega.FetchExternalInput("https://charts.example.com/postgresql-16.3.2.tgz")
if err != nil {
// The error names the URL and the remedy — an unpinned URL reports exactly
// what to pin and how. Surface it as a render failure; do not mask it.
return fmt.Errorf("fetching chart archive: %w", err)
}

무엇이 실패하며, 그 이유.

  • 파일 시스템 또는 네트워크 호출은 호출 경계에서 실패합니다. 게스트에는 미리 열린 디렉터리도 소켓도 없습니다. 이는 파일을 읽으려는 라이브러리 의존성을 포함한 모든 코드 경로에 적용됩니다. 대신 소스 콜백을 통해 소스를 읽으십시오.
  • wasi_snapshot_preview1, extism:host/env, extism:host/user 외의 모듈에 속한 임포트는 로드 시 실패하며, 모듈과 임포트를 명시한 진단이 출력됩니다. 허용된 모듈 내의 개별 WASI 함수 이름은 결코 검열되지 않습니다. 정적으로 링크된 언어 런타임의 사용되지 않는 파일 시스템 및 소켓 임포트는 문제가 없는데, 임포트를 명명하는 것만으로는 아무 권한도 부여되지 않기 때문입니다.
  • lockfile이 고정하지 않은 URL을 가져오면 해당 URL을 명시한 오류와 함께 실패합니다. 해결 방법은 Release의 렌더가 소비하는 모든 외부 입력을 고정하는 aggrega pull --release <release>를 실행한 뒤 빌드하는 것입니다.

아웃바운드 네트워크 접근을 위한 호스트 허용 목록 필드는 없습니다. 플러그인은 빌드 시점에 결코 네트워크에 접근하지 않으며(이것이 AOT(ahead-of-time) 경계입니다), 따라서 작성할 그런 필드도 존재하지 않습니다. 원격 콘텐츠는 앞서 설명한 호스트가 중개하고 다이제스트로 고정된 외부 입력 채널을 통해 도착하며, 주변 네트워크 접근을 통해서는 결코 도착하지 않습니다.

구성. configKV는 런타임이 시작 시 플러그인에 전달하는 문자열 대 문자열 맵입니다. 항목은 작성자 순서를 유지하므로 출력되는 레코드는 실행 간에 바이트 단위로 동일합니다. 없으면 런타임의 기본 빈 구성이 적용됩니다.

5. Plugin 엔티티

플러그인은 Plugin 엔티티로 카탈로그에 들어갑니다. 이 엔티티는 플러그인의 작성 및 메타데이터 표면입니다. 엔티티는 플러그인이 무엇인지 선언하고 .wasm 아티팩트를 가리킵니다. 컴파일러는 플러그인의 동작을 해석하지 않고 고정된 참조를 전달하며, Wasm 런타임이 바이트를 실행합니다.

apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
name: aws-secrets-manager
version: 1.2.0
pluginType: pipeline-step
spec:
abiVersion: v1beta1
pipelineStep:
capabilities:
- helm
- compose
signature:
type: sigstore-cosign
runtime:
maxMemoryPages: 256
timeoutMs: 5000
# hostFunctions is recorded by `aggrega plugin sync` from the .wasm — do not author it.
exports:
- name: fetch
operates: emit
scope: own
selector: external-secret resources for the bound credential

필드는 다음과 같습니다.

  • 아티팩트 위치 필드는 의도적으로 없습니다. 엔티티는 .wasm에 대한 포인터를 갖지 않으며 스키마도 이를 받아들이지 않습니다. 플러그인의 아티팩트 위치는 그 식별자, 즉 리포지토리 경로 plugin/<pluginType>/<name>을 이루는 metadata.pluginType/metadata.name 좌표와, 워크스페이스가 구성된 레지스트리로부터 도출됩니다. 따라서 작성할 위치도, 잘못 쓸 위치도 없습니다. 확인된 콘텐츠 다이제스트는 Release마다 해당 Release의 lockfile에 기록되며, 빌드는 가져온 바이트를 이 다이제스트와 대조해 검증합니다. 식별자는 엔티티에, 검증된 바이트는 lockfile에 있습니다.
  • metadata.version — 엔티티가 게시하는 릴리스로, describe()에서 보고되는 게스트 자체의 빌드 출처 버전과 같아야 합니다. 플러그인 작성자는 빌드 시점에 .wasm의 버전을 정합니다. 빌드가 게스트에 버전을 새기며, 릴리스 태그에서 버전을 가져오는 빌드는 그 태그가 가리키는 커밋에서만 릴리스 버전을 새깁니다. 엔티티의 metadata.version은 바로 그 릴리스를 지정합니다. 게시 단계는 두 값을 교차 검증하고 불일치하면 중단하므로, 엔티티는 항상 자신이 배포하는 바이너리의 정확한 버전을 지정합니다. aggrega plugin gen-catalog --plugin(아래 참조)은 게스트가 보고하는 버전을 생성하는 엔티티에 복사하며, 게스트가 태그된 커밋에서 빌드되었다면 이는 릴리스 버전입니다. 필수입니다.
  • metadata.pluginType — 이 플러그인이 구현하는 소켓 유형으로, provider, linter, pipeline-step, governance, cli, parser, importer 중에서 고릅니다. 플러그인은 정확히 하나를 구현합니다. 이 필드는 주소 지정 블록에서 name, version 옆에 위치하며, 도출된 좌표의 <pluginType> 세그먼트를 제공합니다. 필수입니다.
  • spec.abiVersion — 플러그인이 대상으로 하는 호스트/게스트 ABI 버전입니다. 허용되는 값은 v1beta1이며, 향후 ABI 개정 시 허용 값이 추가됩니다. 필수입니다.
  • 소켓 유형에 해당하는 블록과 그 안의 capabilities — 플러그인은 자신의 metadata.pluginType에 속하는 블록 안에 제공하는 것을 선언하며, 항목의 의미는 이 블록이 정합니다. spec.provider.capabilities는 provider가 제공하는 기능(helm, compose 같은 기능 이름)을 나열합니다. spec.pipelineStep.capabilities는 스텝이 렌더링 출력과 호환되는 provider들을 나열합니다. spec.parser.capabilities는 parser가 읽는 소스 형식을 각각 parse:<format> 형태로 나열합니다. spec.importer.capabilities는 importer가 엔티티 초안을 만드는 외부 형식을 각각 import:<format> 형태로 나열합니다. Go로 작성한 importer는 형식에 의존하지 않는 모든 것, 즉 점수 산정, 참조할지 초안을 만들지의 결정, 초안과 그 렌더링, 설정을 Go 키트의 importer 패키지 github.com/aggrega-ai/aggrega-pdk/go/pkg/importer에서 가져올 수 있습니다. linter, governance, cli 플러그인은 기능을 제공하지 않으며 네 블록 중 어느 것도 갖지 않습니다. 항목은 작성 순서를 유지하며, 모든 목록은 명시적이고 테스트된 주장입니다. 소비자는 나열된 것과 정확히 일치하도록 확인하므로, 플러그인을 실제로 빌드하고 테스트한 대상을 선언하십시오. 파이프라인 스텝의 경우 이 주장은 렌더링 시 강제됩니다. 스텝이 어떤 스코프를 다루면, 그 스코프의 문서를 렌더링하는 provider가 플러그인이 주장하는 목록에 없을 경우 빌드가 중단됩니다. 따라서 빈 목록은 어떤 provider와도 일치하지 않으며 스텝을 어디에도 허용하지 않습니다.
  • spec.signature — 플러그인에 첨부된 서명(8절)을 가리키는 선택적 설명용 포인터입니다. 이 블록은 문서화 용도일 뿐입니다. 카탈로그 독자를 위해 서명이 어디에 있고 어떻게 만들어졌는지 기록하며, 그 자체로 플러그인을 허용하지는 않습니다. 강제하는 검사는 pull 시 적용되는 레지스트리별 신뢰 정책입니다.
  • spec.runtime — 4절의 선택적 실행 제약 블록입니다. 작성자는 maxMemoryPages, timeoutMs, configKV를 작성하며, hostFunctions는 기계적으로 도출되어 aggrega plugin sync가 기록하고 게시 시 검증되므로 작성하지 않습니다.
  • spec.exports — 3절의 export별 기능 주장(name, operates, scope, selector)입니다.

.wasm에서 엔티티 생성하기. 엔티티 중 기계가 소유하는 부분은 직접 작성할 필요가 없습니다. aggrega plugin gen-catalog --plugin <file.wasm>은 게스트의 describe() 자체 보고를 읽고, 이것과 사용자가 제공하는 작은 작성 오버레이(식별자, 런타임 제한, provider 블록)로부터 게시 가능한 Plugin 엔티티를 만듭니다. 생성기는 바이너리가 원천인 필드, 즉 export 주장, 기능 계약, 명령 미러, 호스트 함수 기록을 새기고, metadata.version은 게스트의 describe() 빌드 출처 버전에서 복사하며, 오버레이는 바이너리가 보고하지 않는 것만 제공합니다. 이것이 서드파티 플러그인 작성자를 위해 지원되는 경로입니다. .wasm을 빌드하고 버전을 정한 다음, 엔티티를 다시 생성해 기계 소유 필드가 바이너리와 항상 일치하도록 합니다. 버전은 바이트에 관한 사실이 아니라 릴리스를 지정하는 유일한 복사 필드이므로, 릴리스 태그가 가리키는 커밋의 빌드에서 생성하십시오. 또는 개발 빌드에서 시작했다면, 엔티티를 담은 커밋에 태그를 달기 전에 생성된 엔티티의 metadata.version을 해당 릴리스로 설정하십시오. 빌드 출처 버전이 없는 게스트는 버전이 있는 엔티티로 생성할 수 없으므로, 먼저 빌드 시점에 게스트의 버전을 정하십시오.

엔티티 옆의 .wasm. 플러그인을 작성하는 동안에는 빌드가 가져올 수 있도록 게시된 것이 아직 없으므로, 빌드는 카탈로그 디렉터리에서 플러그인의 Plugin 엔티티 옆에 있는 .wasm을 엔티티의 플러그인 유형과 이름에서 도출된 이름으로 읽습니다. pipeline-step/patch의 경우 pipeline-step--patch.wasm입니다. 소문자, 숫자, 대부분의 하이픈은 그 이름에 그대로 기록되고, 그 밖의 문자는 이스케이프된 형태로 기록되며, 몇몇 위치의 하이픈도 마찬가지입니다 — 따라서 필요한 경우 .wasm이 없을 때의 거부인 A plugin’s .wasm is not on this machine (플러그인의 Wasm 모듈이 이 머신에 없습니다)가 전체 이름을 알려 줍니다. aggrega lint <plugin.yaml> 명령은 바이너리 자체가 플러그인을 포함하고 있지 않은 한 같은 위치 — 전달받은 엔티티 파일 옆, 그 파일이 어느 디렉터리에 있든 — 에서 .wasm을 읽고, .wasm이 보고하지만 엔티티에서 빠진 각 내보내기, 기능 또는 계약마다 알림을 출력합니다. 그곳에 .wasm이 없으면 lint는 찾던 파일과 디렉터리를 밝히며 그 보고를 건너뛰었다고 알리고, 결과는 바뀌지 않습니다.

필드별 참조는 엔티티 페이지 ../entities/plugin.md를 참조하십시오.

6. 플러그인 참조하기

파이프라인 스텝이나 플러그인 소켓은 .wasm 아티팩트를 직접 참조하지 않고, 엔티티의 식별자인 Plugin 엔티티 URI로 플러그인을 참조합니다. 엔티티는 다이제스트 고정, 기능 주장, 런타임 제한, 서명을 담는 계층이며, 소비자는 엔티티를 참조함으로써 이 모두를 받아들입니다.

plugin 필드에 남겨진 단순 .wasm 경로나 원시 아티팩트 참조는 로드 시 거부됩니다. 이와 일치하는 Plugin 엔티티가 없으므로 플러그인 확인이 명시적으로 실패합니다. 엔티티 URI는 필수입니다. 엔티티를 통한 간접 참조는 선택적인 편의 기능이 아니라 계약입니다. FeatureRecipe 파이프라인 스텝은 pipeline[].plugin에 엔티티를 지정합니다. 파이프라인 작성 표면은 ../entities/featurerecipe.md를 참조하십시오.

두 개 이상의 플러그인이 결합되어 있어 공유 핸드오프 계약에 합의해야 하는 경우, 예를 들어 한 플러그인의 출력이 다른 플러그인의 입력이 되는 Fetcher와 Injector 쌍(plugin-contract.md에 설명된 Two-Part Plugin Principle(2부 구성 Plugin 원칙))과 같은 경우에는, 각 플러그인에서 JSON 핸드오프 형태를 개별적으로 다시 기술하지 말고 그 계약을 한 번만 작성한 뒤 각 플러그인이 그 단일 정의에 의존하도록 합니다. 공유 형태는 플러그인들이 주고받는 JSON 구조이며, 두 플러그인이 모두 참조하는 하나의 SchemaLibrary 항목에 둘 수 있습니다. 계약의 출처가 하나이면 계약이 발전하더라도 결합된 플러그인들이 동기화된 상태를 유지합니다. 개별적으로 다시 기술하면 서로 어긋나게 되며, 그 어긋남은 두 플러그인이 런타임에 더 이상 일치하지 않을 때에야 드러납니다. 권장 사항은 Wasm 코드가 아니라 계약을 공유하는 것이며, 각 플러그인은 여전히 별도의 아티팩트로 남습니다.

7. publish → pull → build 수명 주기

플러그인은 세 단계를 거쳐 디스크의 .wasm 파일에서 빌드가 사용할 수 있는 검증된 아티팩트가 됩니다.

게시. aggrega push는 Plugin 엔티티와 그 .wasm을 metadata.version으로 태그된 단일 OCI manifest로 함께 게시합니다. 엔티티 YAML은 manifest의 config blob이 되고 .wasm은 같은 manifest의 레이어로 포함됩니다. 이 쌍을 하나의 태그된 manifest로 게시하기 때문에 push가 원자적으로 이루어지며, 한쪽만 게시되고 다른 쪽은 게시되지 않은 시점이 존재하지 않습니다. 또한 이 때문에 해당 manifest에 대한 하나의 서명이 양쪽을 모두 포함합니다. 양쪽 모두 manifest에 이름이 기록되므로, 버전 태그를 pull하는 일반 OCI 클라이언트는 엔티티를 entity.yaml에, 실행 파일을 entity.wasm에 씁니다.

바이트가 기록되기 전에 게시 단계는 검사를 실행합니다. 먼저 카탈로그 로드와 같은 방식으로 엔티티를 Plugin 스키마에 대해 읽으므로, 시맨틱 버전이 아닌 metadata.version이나 그 밖의 스키마 위반은 .wasm을 읽기 전에 거부됩니다. 그다음 .wasm을 로드하고 그 describe() 자체 보고를 엔티티에 작성된 기능 선언과 교차 검사합니다. 불일치가 있으면 명시적으로 중단되므로, 게시된 엔티티는 함께 배포하는 플러그인이 보고하지 않는 것을 주장하는 일이 없습니다. 커밋되지 않은 변경이 있는 작업 트리에서 빌드한 경우 붙는 -dirty 표시가 describe() 빌드 출처 버전에 포함된 게스트는 거부됩니다. 그 버전이 가리키는 커밋에는 실제로 빌드된 내용이 들어 있지 않기 때문입니다. 커밋에서 빌드한 개발 버전(1.0.0-3-g1a2b3c4)과 사전 릴리스(1.0.0-rc.1)는 게시됩니다. 기록된 metadata.version은 게스트의 describe() 빌드 출처 버전과 교차 검사되며, 둘이 다르면 게시가 중단되므로 두 값은 일치해야 합니다. 두 거부 모두 같은 방법으로 해결합니다. 릴리스 태그가 가리키는 커밋을 깨끗하게 체크아웃하여 플러그인을 빌드하면 플러그인이 릴리스 버전 자체를 보고합니다. 새 릴리스라면 엔티티를 그것이 릴리스하는 소스와 함께 커밋하고 먼저 그 커밋에 태그를 붙입니다. 개발 빌드가 보고하는 버전을 엔티티에 복사하는 것은 해결책이 아닙니다. 그렇게 하면 어떤 릴리스 태그도 가리키지 않는 버전으로 그 빌드가 게시됩니다. .wasm이 가져오는 호스트 함수는 바이너리에서 도출되어 spec.runtime.hostFunctions에 커밋된 기록과 비교됩니다. 차이가 있으면 게시가 중단되고 이 필드를 다시 기록하는 aggrega plugin sync를 안내합니다. 이 필드는 기계가 관리하며 게시는 커밋된 엔티티 파일을 절대 다시 쓰지 않기 때문입니다. 게시된 엔티티는 기록된 호스트 함수 기록을 포함합니다. .wasm 콘텐츠 다이제스트는 이 쌍이 게시되는 manifest의 속성이며, 엔티티에 기록되지 않고 소비자를 위해 Release lockfile에 기록됩니다.

풀. aggrega pull은 Release의 모든 의존성을 해석하고, 모든 카탈로그 엔티티와 원격 아티팩트를 버전과 콘텐츠 다이제스트로 고정하는 Release별 lockfile을 씁니다. 게시된 Plugin은 이 의존성 해석을 통해 해석됩니다. 그 .wasm은 이를 포함하는 manifest와 함께 가져오며, 바이트는 lockfile에 기록된 콘텐츠 다이제스트와 대조하여 검증됩니다. 풀 단계는 검증된 .wasm에서 호스트 함수를 다시 도출하여 기록된 hostFunctions 기록과 대조하고, 둘이 다르면 중단합니다. 이는 다이제스트 고정 위에 더해지는 심층 방어 검사로, 자체 import에서 생성되지 않은 기록을 가진 바이너리를 잡아냅니다. 레지스트리의 신뢰 정책이 서명을 요구하면, 이 단계에서 엔티티의 서명을 가져와 검증하고 lockfile에 검증된 사실로 기록합니다(8절). 검증은 빌드가 아니라 항상 풀 단계에서 이루어지므로 빌드는 AOT 순수성을 유지합니다.

빌드. aggrega build는 해석된 의존성에서 고정되고 검증된 플러그인을 사용합니다. 컴파일러는 다이제스트로 고정된 참조를 전달하고 Wasm 런타임이 바이트를 실행합니다. 로드 게이트는 플러그인이 실행되기 전에 describe() 교차 검사와 호스트 함수 및 런타임 제한 적용을 다시 실행합니다.

8. 서명과 신뢰

Plugin 엔터티는 다른 모든 카탈로그 엔터티와 정확히 같은 방식으로 서명됩니다. 매니페스트의 다이제스트가 서명되어 OCI 리퍼러로 첨부됩니다. .wasm 아티팩트는 별도로 서명되지 않으며, 별도의 서명도 필요하지 않습니다. 이 아티팩트는 다이제스트가 서명되는 바로 그 매니페스트의 레이어이므로 서명이 이를 직접 포괄합니다. .wasm을 변조하면 매니페스트 다이제스트가 바뀌고 서명이 깨집니다.

서명은 게시 시 선택적으로 적용하며, 검증은 풀 시 레지스트리별 신뢰 정책에 의해 강제됩니다. 서명을 요구하도록 구성된 레지스트리는 필요한 서명이 없거나, 신뢰할 수 없거나, 유효하지 않으면 풀을 중단합니다. 엔터티의 spec.signature 블록은 서명이 어디에 있고 어떻게 생성되었는지를 가리키는 문서용 포인터입니다. 이 블록은 카탈로그를 읽는 사람을 위해 사실을 기록할 뿐이며, 그 자체로 수용 여부를 결정하지 않습니다. 수용 여부를 결정하는 것은 풀 시점의 정책입니다.

명령과 해당 플래그는 게시 및 소비 인터페이스와 함께 문서화되어 있습니다. ../cli/aggrega-sign.md, ../cli/aggrega-push.md, ../cli/aggrega-pull.md를 참조하십시오. 이 가이드는 플래그 표를 다시 기술하지 않습니다. 명령 인터페이스는 해당 페이지에서만 다룹니다.

9. 엔터티 버전 관리

Plugin 엔터티는 metadata.version에 엄격한 시맨틱 버전(Semantic Version)을 지닙니다. 게시된 버전은 변경할 수 없습니다. 레지스트리에 이미 존재하는 버전을 다른 내용으로 다시 게시하면 게시 게이트에서 거부됩니다.

플러그인 엔터티를 변경하고 다시 게시하면, 게시 규율은 이전에 게시된 버전과 비교하여 변경을 분류하고 그에 맞는 버전 증가를 요구합니다. 이 분류가 버전 증가 기준표입니다. 문서나 주석만 바뀐 변경은 PATCH이고, 엄격하게 추가만 하는 변경(새 선택적 필드, 새 항목)은 MINOR이며, 제거, 타입 축소, 또는 이전에 선택적이던 필드가 필수가 되는 변경은 MAJOR입니다. 필요 이상으로 버전을 올리는 것은 항상 허용되며, 필요보다 적게 올리면 필요한 버전 증가를 명시하는 진단과 함께 중단됩니다. 엔터티를 처음 게시할 때는 버전 증가 검사를 건너뛰고 검증이 수행되지 않았다는 경고를 표시합니다. 게시 전에 aggrega lint --pre-publish로 검사를 실행하십시오. 전체 기준표와 규칙별 설정은 ../cli/aggrega-lint.md를 참조하십시오.

Plugin에는 extends 표면이 없으므로, 카탈로그의 Components와 Features를 다루는 상속 규칙이 적용되지 않습니다. 버전 증가 기준표와 불변성이 플러그인 엔터티를 다루는 버전 관리 규율입니다.

10. 상호 참조

  • authoring-a-provider-walkthrough.md — 빈 디렉터리에서 렌더링된 출력까지, provider 게스트 하나를 처음부터 끝까지 빌드하는 과정입니다.
  • plugin-contract.md — 플러그인이 대상으로 하는 소켓 지점과 소켓별 입력/출력 형태입니다.
  • policy-socket.md — 거버넌스 소켓에 대한 상세 설명입니다. 네 가지 역할, 판정 심각도, 운영자 입력 채널, 컴파일러에 포함된 두 엔진 중 어느 쪽으로든 정책을 작성하는 방법, 참조 정책 게스트를 다룹니다.
  • core-importers.md — Go 키트의 importer 패키지를 기반으로 한 컴파일러 자체 임포터(읽는 형식마다 하나)입니다. 각 임포터가 읽는 내용, 설정, 그리고 컴파일러 릴리스마다 이루어지는 배포를 다룹니다.
  • ../compatibility.md — 플러그인 키트의 버전 관리 방식과, 한 릴리스를 대상으로 빌드한 플러그인이 다음 릴리스에서도 계속 로드되게 하는 요소를 설명합니다.
  • ../entities/plugin.md — Plugin 엔티티의 필드별 레퍼런스입니다.
  • ../entities/featurerecipe.md — 엔티티 URI로 플러그인을 참조하는 FeatureRecipe의 pipeline: 작성 인터페이스입니다.
  • ../cli/aggrega-lint.md — 배포 린터, 버전 증가 기준표, 불변성 강제를 다룹니다.
  • ../cli/aggrega-inspect.md — Plugin 엔티티의 기능, 런타임 제한, 서명을 검사하는 방법입니다.
  • ../cli/aggrega-push.md, ../cli/aggrega-pull.md, ../cli/aggrega-sign.md — 배포, 사용, 서명 명령 인터페이스입니다.