Plugin
Plugin은 콘텐츠 주소 지정 방식의 WebAssembly 플러그인입니다. 즉, sha256 다이제스트로 고정된 OCI 호스팅 .wasm 아티팩트로서, 자신이 구현하는 소켓 유형, 대상으로 하는 ABI 버전, 선택적 서명 포인터, 선택적 런타임 블록을 선언합니다. 이 엔터티는 플러그인의 작성 및 메타데이터 인터페이스입니다. 의존성 해석은 다이제스트로 아티팩트를 고정하고, 레지스트리별 신뢰 정책은 풀(pull) 시점에 서명을 검증합니다. 컴파일러는 플러그인의 동작을 해석하지 않습니다. 컴파일러는 고정된 참조를 라우팅하고, WebAssembly 런타임이 바이트를 실행합니다.
이 페이지에서는 Plugin 카탈로그 작성 인터페이스를 필드별로 다룹니다. 플러그인이 무엇인지, describe() 자체 보고, publish→pull→build 수명 주기, 서명, 버전 관리 등 작성자의 전체 워크플로는 Wasm 플러그인 개발자 가이드를 참조하십시오. 플러그인이 연결되는 소켓 지점과 그 입력/출력 형태는 Wasm 플러그인 계약을 참조하십시오.
Plugin의 역할
Plugin은 논리적 플러그인 식별자를 구체적인 .wasm 아티팩트에 연결하고, 호스트가 이를 안전하게 로드하고 실행하는 데 필요한 기능 및 런타임 메타데이터에 연결합니다. 파이프라인 단계나 플러그인 소켓은 URI로 이 엔터티를 참조합니다. 엔터티는 선언된 기능, 런타임 제한, 서명 포인터를 담고 있으며, 해석된 콘텐츠 다이제스트는 릴리스 lockfile에 들어 있습니다. .wasm의 위치는 플러그인의 식별자, 즉 metadata.pluginType과 접두사 없는 metadata.name으로 구성되는 주소 지정 좌표 plugin/<pluginType>/<name>에 구성된 레지스트리를 더한 값에서 도출되며, 작성하는 필드가 아닙니다. 엔터티를 통한 간접 참조는 필수입니다. 접두사 없는 .wasm이나 아티팩트 참조는 일치하는 엔터티가 없으므로 로드 시 거부됩니다.
Plugin의 선언은 소켓 유형별로 묶이며, 엔터티를 읽는 일은 이 묶음에서 시작합니다.
- 소켓 유형당 블록 하나:
spec.provider,spec.pipelineStep,spec.parser,spec.importer. 플러그인은 자신의metadata.pluginType이 지정하는 블록 하나를 가지며, 모든 블록에는capabilities:목록이 있습니다. 이 목록은aggrega plugin gen-catalog가 플러그인 자체의describe()에서 기록한 것이며, 그 의미는 그 블록에만 속합니다. provider의 목록은 제공하는 기능을 지정하고, 파이프라인 단계의 목록은 해당 단계와 호환되는 provider 기능을 지정하며, parser와 importer의 목록은parse:<format>과import:<format>으로 작성하는 소스 형식을 지정합니다. 의미를 전달하는 것은 포함 관계입니다. 기능 항목은 그것이 어떤 종류의 주장인지 알려 주는 블록을 먼저 읽지 않고는 접근할 수 없습니다. - provider 블록은 목록 이상의 것을 담습니다:
spec.provider는 플러그인이 Workload 종류를 어떻게 변환하는지, 어떤 플랫폼 고유 어노테이션을 읽는지, 그리고 렌더링 동작 계약(spec.provider.contract: 입력 종류, 경계 조립, 아티팩트 구분자, 인스턴스 재사용)도 선언합니다. 이들은 제공되는 차원이 아니라 렌더링 동작을 설명하므로, provider의 기능 목록 안이 아니라 그 옆에 놓입니다. - 횡단 관심사 소켓은 기능을 선언하지 않습니다:
linter,governance,cli플러그인은 렌더링 차원도 소스 형식도 제공하지 않으므로 네 블록 중 어느 것도 가지지 않습니다.
apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: aws-secrets-manager version: 1.2.0 pluginType: pipeline-stepspec: abiVersion: v1beta1 pipelineStep: # capabilities is recorded by `aggrega plugin gen-catalog` from the plugin's describe(); an author may narrow it. 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 credentialmetadata
표준 카탈로그 메타데이터입니다. name, version, pluginType은 필수이며, version은 엄격한 시맨틱 버전(예: 1.2.0)입니다. 선택 필드인 description, maintainers, license, repository, home, keywords는 모든 카탈로그 엔터티가 갖는 것과 같은 형태를 따르며, metadata는 다른 키를 받지 않습니다. 게시된 버전은 변경할 수 없으며, 기존 버전을 다시 게시하면 게시 게이트에서 거부됩니다.
metadata.name은 접두사 없는 이름이며, 소켓 접두사를 갖지 않습니다. 플러그인의 주소 지정 좌표 plugin/<pluginType>/<name>은 metadata.pluginType과 접두사 없는 metadata.name에서 파생되며, 이름 안에 직접 작성하지 않습니다.
metadata.pluginType
이 플러그인이 구현하는 소켓 유형입니다. 플러그인 정체성의 일부이므로 주소 지정 블록에서 name 및 version 옆에 위치하며, 파생되는 plugin/<pluginType>/<name> 좌표의 <pluginType> 세그먼트를 제공합니다. 플러그인은 런타임이 인식하는 플러그인 유형 분류에서 선택한 정확히 하나의 소켓 유형을 구현합니다.
provider— IR 노드를 프로바이더 고유의 아티팩트로 렌더링합니다.linter— 작성된 콘텐츠를 검사하고 진단을 발생시킵니다.pipeline-step— FeatureRecipe 또는 Recipe의pipeline:안에서 렌더링된 문서 집합에 패치를 적용하는 단계입니다.governance— 빌드 파이프라인의 거버넌스 역할을 수행합니다. 토폴로지 구성 단계에서는 토폴로지 그래프 노드 레이블을 자동으로 태그하며, 호스트가 그래프의 레이블 전용 투영에 적용하는 JSON Patch 문서를 반환합니다. 정적 분석 단계나 렌더 단계에서는 IR 그래프 또는 렌더링된 아티팩트를 평가하여 수락/거부 판정을 반환하며, 실패한 규칙은 빌드를 중단시킵니다. 무엇을 내보낼 수 있는지는 종류가 아니라 연결된 역할이 결정합니다.parser— 외부 소스 형식(HCL, TOML, YAML, JSON, …)을 구조화된 JSON 트리로 파싱합니다. 따라서 컴파일러가 기본적으로 파싱하지 않는 형식을 읽어야 하는 소비자는 원시 텍스트 대신 파싱된 트리를 바탕으로 작업합니다.importer— 외부 인프라 또는 에이전트 정의 소스를 Aggrega 작성 파일 초안으로 변환하며, 처리하는 형식을import:<format>기능으로 알립니다.cli— 운영자가 명령줄에서 호출하는 런타임aggrega <cmd>하위 명령을 제공합니다. 컴파일 타임의 렌더 소켓 및 파이프라인 소켓과 구별되는 런타임 소켓입니다.
필수입니다.
spec.abiVersion
플러그인이 대상으로 하는 호스트/게스트 ABI 버전입니다. 허용되는 값은 v1beta1이며, 새로운 ABI 개정이 값을 하나 추가합니다. 필수입니다.
기능 선언: 소켓 유형마다 하나의 블록
기능(capability) 은 소비자가 플러그인에 요청하는 것으로, Recipe가 요청하는 렌더 기능이나 빌드가 읽어야 하는 소스 형식이 이에 해당합니다. 플러그인의 기능은 자신의 소켓 유형에 속한 블록 안에 기록되므로, 목록이 어느 블록에 있는지가 그 항목의 의미를 결정합니다:
metadata.pluginType | 기능이 선언되는 위치 | 항목이 가리키는 것 |
|---|---|---|
provider | spec.provider.capabilities | 이 플러그인이 제공하는 렌더 기능(예: helm 또는 compose). |
pipeline-step | spec.pipelineStep.capabilities | 이 플러그인의 단계가 렌더링된 출력과 호환되는 provider. |
parser | spec.parser.capabilities | 이 플러그인이 읽는 소스 형식으로, parse:<format> 형태로 작성합니다. |
importer | spec.importer.capabilities | 이 플러그인이 엔티티 초안을 만들어 내는 외부 소스 형식으로, import:<format> 형태로 작성합니다. |
linter, governance, cli | — | 없음. 이 소켓들은 어떤 기능도 제공하지 않으므로 네 블록 중 어느 것도 갖지 않습니다. |
플러그인은 정확히 하나의 소켓 유형을 구현하므로 그 엔터티는 블록 하나를 가집니다. 목록은 플러그인 자체의 보고입니다. aggrega plugin gen-catalog가 플러그인의 describe()를 읽고, 보고된 각 기능을 블록에 기록합니다. 작성자는 게시 전에 목록을 좁혀, 플러그인이 보고하지만 게시되는 엔터티가 제공해서는 안 되는 기능을 뺄 수 있습니다. aggrega validate <entity> --plugin <file.wasm>과 aggrega push는 좁혀진 목록을 받아들이고, 플러그인이 보고했지만 목록에서 빠진 각 기능을 지목하는 알림을 출력합니다. 둘 다 플러그인이 보고하지 않는 기능을 지정하는 목록은 받아들이지 않습니다. 둘 다 그런 목록을 거부하며 해당 기능 각각과 플러그인이 실제로 보고하는 기능을 지목하므로, 게시된 목록이 플러그인이 제공하는 것보다 더 많은 것을 제공하는 일은 없습니다. 플러그인이 helm과 helm-chart를 보고하는데 compose까지 나열한 pipeline-step 엔터티는 다음과 같이 거부됩니다:
[E0080] entity "probe-step:1.0.0-rc.1" lists capabilities ["compose"], which the plugin's describe() does not report (it reports ["helm" "helm-chart"]); remove them from the list, which may name only capabilities the plugin reports: wasm: entity contract claim does not match plugin describe()소비자는 나열된 것에 대해서만 정확히 해석합니다.
spec.provider
pluginType: provider 플러그인의 provider 소켓 블록입니다. 플러그인이 제공하는 기능, 플랫폼이 소유한 aggrega.ai/v1beta1 Workload kind를 변환하는 방식, 읽는 플랫폼 고유 어노테이션, 그리고 렌더링 동작 계약을 담습니다. 이 블록은 provider 렌더링을 수행하는 모든 플러그인에 존재하며 다른 모든 플러그인 유형에는 없습니다. Workload 합성 없이 sourced 또는 artifact 콘텐츠만 렌더링하는 provider도 이 블록을 가집니다. 이 경우 기능과 계약은 그곳에 선언하고 workloadSchema만 생략합니다.
spec.provider.capabilities
이 provider가 제공하는 기능으로, helm이나 compose 같은 기능 이름이며 provider는 그 출력 형태를 렌더링합니다. provider는 모든 기능에 걸쳐서가 아니라 한 기능의 출력 형태를 공유하는 아티팩트들에 걸쳐 범용적이므로, 이 목록은 플러그인 자체가 보고하는 기능을 지정합니다. aggrega plugin gen-catalog가 플러그인의 describe()에서 이를 기록하며, 작성자는 게시 전에 이를 좁힐 수 있습니다. 항목은 기록된 순서를 유지합니다.
Recipe가 요청한 provider 대상(spec.capability: helm)은 목록에 그 대상을 포함하는 provider 플러그인으로 해석됩니다. 둘 이상의 provider 플러그인이 같은 대상을 나열하면 워크스페이스가 선택합니다. 워크스페이스 구성의 plugins.providers 선택이 사용할 플러그인을 지정하며, 이는 aggrega pull 시점에 해석되어 lockfile에 기록됩니다. 선택이 없고 후보가 정확히 하나이면 그 후보가 사용되고, 선택이 없고 후보가 둘 이상이면 빌드가 중단되며 모든 후보를 나열합니다. 모호성은 카탈로그 전체의 고유성 규칙이 아니라 사용 시점에 워크스페이스별로 해소됩니다. 목록이 비어 있거나 없으면 기능 주장을 선언하지 않는 것이므로 플러그인은 어떤 대상도 제공하지 않습니다.
여기서 기능 이름에는 콜론이 들어가지 않습니다. Recipe의 spec.capability는 마지막 콜론까지를 기능으로, 그 뒤를 버전 고정으로 읽으므로 콜론이 포함된 이름은 결코 요청될 수 없습니다. describe()가 그런 이름을 보고하는 플러그인은 로드 시 거부되며, 그로부터 게시용 엔티티가 생성되지 않습니다. pipeline-step 플러그인이 나열하는 provider 기능에도 동일하게 적용됩니다. 파서의 parse:<format>과 임포터의 import:<format>에 있는 콜론은 해당 이름의 일부이므로 그대로 유지됩니다.
spec.provider.workloadSchema
이 provider가 aggrega.ai/v1beta1 Workload kind를 provider 고유 매니페스트로 변환하는 방식을 문서화하는 JSON Schema 2020-12 선언입니다. 합성을 수행하는 provider에 관례에 따라 선언됩니다. 그러한 provider는 문서화된 변환 계약으로 workloadSchema를 선언하여, provider가 소비하는 Workload 필드, 각 열거형 필드가 허용하는 닫힌 집합, 적용되는 범위 제약을 기술합니다.
본문은 Plugin이 로드될 때 JSON Schema 2020-12로 컴파일됩니다. 이는 잘못된 스키마를 렌더링 시점이 아니라 로드 시점에 거부하는 구조적 안전장치입니다. workload: Recipe의 지원 여부는 이 필드의 존재가 아니라 바인딩된 provider의 합성 능력으로 결정됩니다. 합성을 할 수 없는 provider에 바인딩된 합성 모드 Recipe는 렌더링 시점에 명시적으로 중단됩니다. 표준 라이브러리 카탈로그는 workloadSchema를 provider 기능과 동기화된 상태로 유지합니다. 이 필드는 문서화된 계약이며, 그 외에 이를 읽는 것은 없습니다. Workload 본문 자체는 이 provider별 필드가 아니라 플랫폼이 소유한 내장 Workload 스키마에 대해 검증됩니다.
spec.provider.wellKnownAnnotations
이 provider가 읽는 플랫폼 고유의 잘 알려진 어노테이션 키(예약된 aggrega.ai/ 네임스페이스 아래의 키)와 각 키가 없을 때 적용되는 동작을 열거하는 순서 있는 배열입니다. 각 항목은 key(provider가 읽는 어노테이션, 예: aggrega.ai/namespace), purpose(어노테이션이 있을 때 제어하는 내용), 선택 사항인 defaultBehavior(어노테이션이 없을 때 provider가 하는 동작), 그리고 provider가 키를 읽는 위치를 나열하는 선택 사항인 scope(Recipe 입력 종류인 sourced, synthesized 또는 artifactsStandalone, 혹은 경계마다 한 번 읽는 키의 경우 boundary)를 가집니다. key와 purpose는 필수이며, 항목은 작성자가 지정한 순서를 유지합니다.
이 필드는 provider의 지원 선언이며, 컴파일러는 이를 두 가지 방식으로 읽습니다. scope가 블록 자체의 contract.inputKinds가 주장하지 않는 입력 종류를 지정하는 항목은 그 주장과 모순되므로 Plugin이 거부되며, 해당 키와 범위가 지목됩니다. 또한 빌드가 이 provider를 통해 렌더링할 때, 그 렌더링이 선언하는 어떤 입력 종류에서도 항목이 다루지 않는 aggrega.ai/ 어노테이션은 키, provider, 그리고 그 입력 종류들을 지목하는 경고를 일으킵니다. 값은 그대로 전달되며 빌드는 중단되지 않습니다. 필드가 없으면 아무것도 선언하지 않으며, 이 provider에 대해 그러한 경고는 발생하지 않습니다. 스키마 검증은 각 항목의 형태(키가 aggrega.ai/ 네임스페이스 아래에 있고 purpose가 있는지)만 확인하며, 이는 예약된 네임스페이스에 값을 바인딩하는 것을 관장하는 런타임 검사와는 별개입니다.
metadata: pluginType: providerspec: abiVersion: v1beta1 provider: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - helm workloadSchema: | # how the Workload kind translates to this provider's native output ... wellKnownAnnotations: - key: aggrega.ai/namespace purpose: Overrides the target namespace the provider renders into. defaultBehavior: Renders into the boundary's default namespace.표준 라이브러리 provider가 제공하는 provider별 어노테이션 집합과 workloadSchema 내용은 ../providers/well-known-annotations.md, ../providers/helm.md, ../providers/helm-chart.md, ../providers/compose.md에 문서화되어 있습니다.
spec.provider.readsNoWellKnownAnnotations
이 provider가 플랫폼 고유의 잘 알려진 어노테이션 키를 하나도 읽지 않음을 선언합니다. 이는 어떤 키도 다루지 않는 지원 선언이며, 이 필드와 wellKnownAnnotations를 모두 생략하는 것으로는 말할 수 없는 것을 말합니다. 선언이 없는 것은 침묵이지만, 이 선언은 예약된 aggrega.ai/ 네임스페이스 아래의 어떤 것도 읽지 않는다는 provider 자신의 진술입니다. 그러한 provider를 통해 렌더링하는 빌드는 렌더링에 도달하는 모든 aggrega.ai/ 어노테이션에 대해 키, provider, 그리고 렌더링이 선언하는 입력 종류를 지목하며 경고합니다. 값은 그대로 전달되며 빌드는 중단되지 않습니다.
true만 작성할 수 있으므로, 아무것도 말하지 않는 유일한 방법은 여전히 필드를 생략하는 것입니다. wellKnownAnnotations와 함께 작성할 수 없습니다. 일부 키를 읽는 provider는 대신 그 키들을 그곳에 나열합니다. 두 거부 모두 스키마 수준이므로, Plugin은 읽히는 시점에 거부됩니다.
spec: provider: capabilities: - terraform readsNoWellKnownAnnotations: true표준 라이브러리의 terraform provider가 이를 선언합니다. 이것이 그 provider를 통해 렌더링되는 Release에 무엇을 의미하는지는 ../providers/terraform.md에서 설명합니다.
spec.provider.contract
provider 렌더링 플러그인이 스스로 선언하는 컴파일 타임 렌더 동작 계약입니다. 렌더하는 입력 종류, 디스패치 그룹의 노드별 출력을 조립하는 방식, 가져온 아티팩트 파일에 적용하는 템플릿 구분자 쌍, 로드된 인스턴스 하나가 모든 크로싱을 처리할 수 있는지 여부, omit 항목을 따르는지 여부, 그리고 Recipe가 해당 경계의 공유 출력에 기여하는 파일을 받아들이는지 여부를 담습니다. 같은 블록에서 capabilities 옆에 있지만 다른 질문에 답합니다. capability 목록은 이 플러그인이 어떤 capability를 제공하는지를 말하고, 계약은 그것을 어떻게 렌더하는지를 말합니다. aggrega plugin gen-catalog가 플러그인 자체의 describe() 자체 보고에서 이 계약을 기록하고, 호스트는 게시 시점과 로드 시점에 그 자체 보고와 교차 검증하며, 불일치하면 중단됩니다. 없으면 렌더 동작 계약을 선언하지 않은 것이며, 교차 검증은 export별 주장만 비교합니다. 모든 필드는 선택 사항입니다.
| 필드 | 효과 |
|---|---|
inputKinds | 플러그인이 렌더하는 세 가지 Recipe 입력 종류이며, 각각 독립적인 boolean 주장입니다. sourced(소스 파일 집합 — 차트, 모듈, compose 파일), synthesized(합성된 Workload), artifactsStandalone(가져온 아티팩트 문서를 담고 소스나 workload가 없는 독립 노드)입니다. 호스트는 노드의 입력 종류를 이 집합에 비추어 허용 여부를 결정합니다. |
boundaryAssembly | 플러그인이 디스패치 그룹의 노드별 렌더 출력을 결합하는 방식입니다. none은 각 노드의 출력을 디스패치 경로에 직접 씁니다. merge는 노드별 조각을 하나의 문서로 합칩니다. nest는 각 노드의 출력을 상위 구조 안의 고유한 위치 아래에 둡니다. 없으면 조립 주장이 없습니다. |
artifactDelimiters | 플러그인이 가져온 아티팩트 파일에 적용하는 Go 템플릿 구분자 쌍으로, left와 right로 지정합니다. 없으면 기본 {{/}} 쌍을 뜻합니다. 대상 구문이 이 쌍과 충돌하는 플러그인은 대체 쌍(예: [[/]])을 선언합니다. |
reusableInstance | 크로싱마다 새 인스턴스를 쓰는 대신 로드된 플러그인 인스턴스 하나가 빌드의 모든 render, assemble, validate 크로싱을 처리할 수 있는지 여부입니다. 플러그인이 크로싱 간에 상태를 유지하지 않아 단일 인스턴스가 재사용되든 새로 로드되든 바이트 단위로 동일한 출력을 만드는 경우에만 true로 선언합니다. 없으면(false) 크로싱마다 새 인스턴스를 로드하여, 구조상 상태를 갖는 플러그인을 격리합니다. aggrega build --verify-determinism은 각 노드를 두 번 렌더하고 차이가 있으면 중단함으로써 재사용 가능한 플러그인의 출력이 안정적임을 증명합니다. |
omits | 플러그인이 omit 항목, 즉 노드 출력에서 제외할 렌더 단위를 지정하는 항목을 따르는지 여부입니다. 플러그인은 항목과 일치하는 모든 단위를 렌더 결과에서 제외하고, 각 항목이 몇 개의 단위와 일치했는지 보고합니다. 이 값은 플러그인의 describe()가 보고하는 주장을 기록하므로, true는 이를 보고하는 플러그인에만 맞으며, 보고와 다른 값이면 중단됩니다. 없으면(false) 그러한 지원을 선언하지 않습니다. |
boundaryArtifacts | 플러그인의 대상이 Recipe의 spec.boundary.artifacts에 따라 Recipe가 렌더되는 경계의 공유 출력에 기여하는 파일을 받아들이는지 여부입니다. 컴파일러는 그러한 파일을 플러그인이 해당 경계에 대해 조립하는 결과 옆에 한 번씩 쓰고, 대상은 이를 그 출력의 일부로 읽습니다. 이 값은 플러그인의 describe()가 보고하는 주장을 기록하며, 보고와 다른 값이면 중단됩니다. 없으면(false) 그러한 지원을 선언하지 않으며, 이 플러그인에 대해 이 블록을 선언한 Recipe는 렌더가 시작되기 전에 거부됩니다. |
metadata: pluginType: providerspec: provider: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - helm-chart contract: inputKinds: sourced: true synthesized: false artifactsStandalone: false boundaryAssembly: nest artifactDelimiters: left: "[[" right: "]]" reusableInstance: truespec.pipelineStep
pluginType: pipeline-step 플러그인의 파이프라인 단계 블록입니다. 유일한 필드인 capabilities는 플러그인의 단계가 변환할 수 있는 렌더링 출력을 내는 provider들을 지정하며, helm이나 compose 같은 capability 이름으로 씁니다. 단계는 한 번에 하나의 provider 출력 형태를 대상으로 작성되므로, 이 목록은 플러그인 자체가 보고하는 provider를 지정합니다. 항목은 기록된 순서를 유지합니다. 이 블록은 파이프라인 단계 플러그인에만 존재합니다.
이 블록은 카탈로그에서 읽을 수 있는 해당 주장의 기록입니다. aggrega plugin gen-catalog가 플러그인 자체의 describe() 자기 보고에서 이를 기록하며, 작성자는 게시 전에 이를 좁힐 수 있습니다. 강제 적용은 같은 주장을 플러그인에서 읽습니다. 단계가 어떤 범위에 적용될 때, 그 범위의 문서를 렌더링하는 provider가 플러그인이 주장하는 provider 중에 없으면 빌드가 중단됩니다. 목록이 비어 있거나 없으면 호환성 주장을 선언하지 않은 것이므로 어떤 범위도 해당 단계를 허용하지 않습니다.
metadata: pluginType: pipeline-stepspec: abiVersion: v1beta1 pipelineStep: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - helm - composespec.parser
pluginType: parser 플러그인의 파서 블록입니다. 유일한 필드인 capabilities는 플러그인이 정규 구조화 트리로 변환하는 소스 형식을 나열하며, 각 항목은 parse:<format> 형태로 작성합니다. 접두사는 항목의 일부이므로 여러 형식을 읽는 플러그인은 형식마다 항목을 하나씩 나열합니다. aggrega plugin gen-catalog가 플러그인 자체의 describe()에서 목록을 기록하고, 작성자는 게시 전에 이를 좁힐 수 있으며, 항목은 기록된 순서를 유지합니다. 이 블록은 파서 플러그인에만 있습니다.
요청된 형식은 목록에 일치하는 항목이 있는 파서로 결정됩니다. 어떤 파서도 알리지 않는 형식은 빌드를 중단시키고, 둘 이상의 파서 플러그인이 알리는 형식은 후보를 나열하며 모호함으로 중단됩니다. 파서에는 대신 사용할 무설정 기본값이 없으므로 대체 동작은 없습니다. 목록이 비어 있거나 없으면 형식에 대한 선언이 없는 것이므로 플러그인은 아무것도 파싱하지 않습니다.
metadata: pluginType: parserspec: abiVersion: v1beta1 parser: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - parse:hcl - parse:tomlspec.importer
pluginType: importer 플러그인의 importer 블록입니다. capabilities 필드는 플러그인이 Aggrega 작성 파일 초안으로 변환하는 외부 소스 형식을 나열하며, 각 항목은 import:<format> 형태로 작성합니다. 접두사는 항목의 일부이므로 여러 형식을 처리하는 플러그인은 형식마다 항목을 하나씩 나열합니다. aggrega plugin gen-catalog가 플러그인 자체의 describe()에서 목록을 기록하고, 작성자는 게시 전에 이를 좁힐 수 있으며, 항목은 기록된 순서를 유지합니다. 이 블록은 importer 플러그인에만 있습니다.
요청된 import 형식은 목록에 일치하는 항목이 있는 importer로 확정됩니다. 어떤 importer도 알리지 않는 형식은 import를 중단시키고, 둘 이상의 importer 플러그인이 알리는 형식은 후보를 명시하며 모호함으로 중단됩니다. 단, 워크스페이스 구성의 plugins.importer 항목이 그중 하나를 연결하면 그 importer가 실행됩니다. 목록이 비어 있거나 없으면 어떤 형식도 주장하지 않으므로 플러그인은 아무것도 가져오지 않습니다.
detect 필드는 import가 형식을 지정하지 않을 때 해당 형식의 소스를 인식하는 데 쓰이는 시그니처를 기록합니다. 이 필드는 호스트 함수 및 명령 기록과 마찬가지로 기계가 관리합니다. 엔티티가 플러그인에서 생성될 때 플러그인의 describe()가 보고하는 내용에서 플러그인이 시그니처를 선언한 순서대로 도출되며, 작성자는 이를 작성하지 않습니다. 각 시그니처는 다음을 지정합니다.
syntax— 소스를 파싱하는 구문 형식으로, parser 플러그인이parse:<syntax>로 알리는 형식입니다. 예:json,yaml.files— 선택 사항인 파일 이름 패턴으로, 소스 이름의 끝부분과 대조합니다. 세그먼트가 하나인 패턴은 파일 자체의 이름과, 슬래시로 구분된 세그먼트가 여러 개인 패턴은 경로의 마지막에서 같은 수의 세그먼트와 대조합니다. 따라서.vscode/mcp.json은.vscode라는 디렉터리에 있는mcp.json이라는 파일과 일치합니다.*,?,[...]는 한 세그먼트 안에서 일치합니다. 이 필드가 없으면 시그니처는 이름과 관계없이 단일 파일인 소스에 적용되며, 디렉터리의 어떤 파일에도 적용되지 않습니다. importer 시그니처의 패턴은aggrega import가 디렉터리의 어떤 파일을 그 importer에 넘길지도 결정합니다.match— 파싱된 트리가 모두 충족해야 하는 조건식입니다. 각 조건식에는 트리 최상위부터 키를 점으로 연결한path(정수 세그먼트는 배열 위치를 선택),present,absent,object,array,string,number,boolean중 하나인is, 그리고 선택적으로 값이 정확히 일치해야 하는 문자열인equals또는 값이 시작해야 하는 문자열인prefix가 있습니다. 두 가지 중 최대 하나만 지정할 수 있습니다.
import가 형식을 지정하지 않으면 워크스페이스 카탈로그에 있는 모든 importer(모든 버전 포함)와 컴파일러의 핵심 importer의 시그니처를 소스와 대조합니다. 소스는 그 이름에 적용되는 시그니처가 읽는 구문마다 한 번씩 파싱되며, 이때 워크스페이스 카탈로그가 해당 구문에 제공하는 parser를 사용하고, 카탈로그가 parser를 제공하지 않는 구문에는 컴파일러 자체에 포함된 parser를 사용합니다. 어떤 구문으로 파싱되지 않는 소스는 그 구문을 지정한 시그니처와 일치하지 않습니다. 디렉터리는 그 파일을 통해 대조됩니다. 각 시그니처는 그 패턴이 선택하는 디렉터리의 파일과 이름 순서대로 대조되며, 패턴을 선언하지 않은 시그니처는 어떤 파일에도 적용되지 않습니다. 시그니처와 일치하는 소스는 그 importer가 알리는 모든 형식으로 인식됩니다. 인식된 형식이 정확히 하나이면 소스는 그 형식으로 읽힙니다. 어떤 시그니처와도 일치하지 않는 소스는 거부되며, 형식을 요청하고 importer가 알리는 형식을 제시합니다. 다만 디렉터리의 경우에는 그 파일 중 하나를 단독으로 지정하거나 파일 패턴을 선언한 importer의 형식을 지정하도록 요청하며, 그 형식들만 제시합니다. 둘 이상의 형식으로 인식된 소스는 그 형식들을 명시하며 More than one importer recognises the source (둘 이상의 importer가 소스를 인식함) 조건으로 거부됩니다. 따라서 둘 이상의 형식을 알리는 importer는 시그니처와 일치하는 모든 소스가 모호함으로 거부되므로, 소스가 인식되어야 하는 importer는 형식 하나만 제공합니다.
엔티티가 detect를 기록하는 경우, 그 내용은 플러그인의 describe()가 보고하는 내용과 시그니처 단위로 순서까지 같아야 합니다. importer를 로드할 때 보고 내용이 다른 플러그인은 importer.detect를 명시하며 거부되고, 게시할 때도 마찬가지입니다. detect를 기록하지 않은 엔티티는 아무것도 주장하지 않으므로 비교되지 않고, 플러그인의 describe()가 보고하는 시그니처를 그대로 로드하며, 이 경우 해당 importer의 형식은 이름을 지정해야만 사용할 수 있습니다.
metadata: pluginType: importerspec: abiVersion: v1beta1 importer: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - import:langflow detect: - syntax: json match: - path: data.nodes is: arrayspec.signature
플러그인에 첨부된 서명을 가리키는 선택적 설명용 포인터입니다. 이 블록은 문서화 용도일 뿐입니다. 카탈로그를 읽는 사람을 위해 서명이 어디에 있고 어떻게 생성되었는지를 기록하며, 블록 자체가 플러그인을 허용하지는 않습니다. 강제되는 검사는 pull 시점에 적용되는 레지스트리별 신뢰 정책입니다. 서명은 OCI referrer로 가져와 레지스트리의 신뢰된 ID 또는 고정된 키에 대해 검증되고, lockfile에 검증된 사실로 기록됩니다. 서명을 요구하는 레지스트리는 필요한 서명이 없거나, 신뢰할 수 없거나, 유효하지 않으면 pull을 중단합니다.
type— 서명 방식입니다. 지원되는 방식은sigstore-cosign입니다. 블록이 있을 때 필수입니다.signatureRef— 첨부된 서명 번들의 OCI referrer 참조로, 문서화와 탐색을 위한 것입니다. 서명을 여기에 고정하지 않고 pull 시점에 referrer 열거로 찾는 경우에는 없습니다.publicKeyRef— 키 기반 서명의 경우 서명 생성에 사용된 공개 키를 가리키는 포인터입니다. 없으면 키리스(OIDC ID) 서명임을 나타내며, 레지스트리의 신뢰된 ID에 대해 검증됩니다.
spec.runtime
호스트가 플러그인을 로드하고 실행할 때 적용하는 선택적 실행 제약입니다. 아웃바운드 네트워크 접근은 작성 필드가 아닙니다. 플러그인은 빌드 시점에 네트워크에 접근하지 않으므로(AOT(ahead-of-time) 경계) 여기에는 호스트 허용 목록 필드가 없습니다. 플러그인에 필요한 원격 콘텐츠는 Release의 lockfile에 기록되는, 호스트가 중개하고 다이제스트로 고정된 외부 입력 채널을 통해 전달되며, 주변 네트워크 접근을 통해서는 결코 전달되지 않습니다. fetch 래퍼와 고정 규율은 개발자 가이드에서 설명합니다.
| 필드 | 효과 |
|---|---|
maxMemoryPages | 플러그인의 선형 메모리를 Wasm 페이지 단위(페이지당 64 KiB)로 제한합니다. 0이거나 없으면 플랫폼 기본 상한이 적용되므로 로드가 무제한이 되는 일은 없습니다. 더 많은 메모리가 필요한 연결은 이 값을 높입니다. |
timeoutMs | 한 번의 호출 동안 플러그인 자체 코드가 실행될 수 있는 시간을 밀리초 단위로 제한하며, 플러그인이 호출하는 호스트 함수 안에서 소요된 시간은 포함하지 않습니다. Linux에서는 프로세서 시간으로 측정하므로 바쁜 머신에서 프로세서를 기다리는 시간은 포함되지 않습니다. 다른 시스템에서는 경과 시간으로 측정합니다. 새로 로드된 플러그인에 대한 첫 호출에는 플러그인 자체의 시작 시간도 포함됩니다. 0이거나 없으면 플랫폼 기본 상한이 적용되므로 호출을 취소할 수 없게 되는 일은 없습니다. 더 오래 실행되는 연결은 이 값을 높입니다. |
hostFunctions | 플러그인이 임포트하는 호스트 함수 이름입니다. 기계적으로 도출되는 읽기 전용 값이므로 직접 작성하지 마십시오. aggrega plugin sync는 .wasm 임포트 섹션에서 호스트 함수를 읽어 이 필드에 기록하고, publish는 바이너리와 다른 기록을 거부하며, 이 값은 게시된 바이너리를 반영하고 관리되는 허용 목록에 대해 검증됩니다. 호스트는 정확히 이 집합만 등록하여, 각 플러그인에 그 바이너리가 필요로 하는 최소 권한의 호스트 표면을 제공합니다. pull은 기록된 값을 다시 도출하여 바이너리와 대조해 검증합니다. 게시 전에 값을 미리 보려면 aggrega inspect --plugin <file.wasm>을 실행합니다. |
configKV | 런타임이 시작 시 플러그인에 전달하는 Plugin별 구성으로, 문자열-문자열 키/값 쌍입니다. 항목은 작성자가 작성한 순서를 유지하므로 출력되는 레코드는 실행할 때마다 바이트 단위로 동일합니다. 없으면 런타임의 기본 빈 구성이 적용됩니다. |
spec.exports
플러그인이 제공하는 export와 각 export에 선언된 capability를 작성자 순서를 유지하는 순서 있는 목록으로 나타냅니다. export는 호스트가 디스패치하는 이름 있는 진입점 하나입니다(예: render_node, lint_naming, step). export별 capability 블록은 해당 export가 수행하는 작업을 나타내며, aggrega plugin gen-catalog가 플러그인의 describe() 자기 보고에서 이를 기록하고, 호스트는 게시 시점과 로드 시점에 그 자기 보고와 교차 검증합니다. 생략하면 작성된 export 표면을 선언하지 않습니다.
| 필드 | 효과 |
|---|---|
name | export의 ABI 이름, 즉 호스트가 디스패치하는 이름입니다. 각 항목에 필수입니다. |
operates | export가 수행하는 파이프라인 작업으로, patch(기존에 렌더링된 문서 수정) 또는 emit(새 문서 추가)입니다. 호스트는 이 값을 플러그인의 자기 보고와 교차 검증합니다. 이 값은 검증되는 capability 선언이며 디스패치 스위치가 아닙니다. 스텝이 수행하는 작업은 게스트가 반환하는 결과가 전달합니다. 생략하면 작업 선언을 전달하지 않습니다. |
scope | export가 작업하는 문서 루트로, own(노드 자체의 렌더링된 문서) 또는 host(component 범위 FeatureRecipe가 연결된 component의 문서)입니다. 호스트는 스텝 실행 전에 선언된 범위를 읽어, 해당 범위를 렌더링하는 provider에 대한 provider 호환성을 적용합니다. 생략하면 기본값은 own입니다. |
selector | export가 작용하는 대상을 사람이 읽을 수 있도록 자유 형식으로 기술한 설명입니다(예: workloads carrying a pod template). 카탈로그 독자와 inspect 표면을 위한 문서이며, 컴파일러는 이를 해석하지 않습니다. |
spec.commands
cli 플러그인이 제공하는 최상위 aggrega <command> 동사를 플러그인의 describe() 자기 보고가 선언한 순서를 유지하는 순서 있는 목록으로 나타냅니다. 머신이 소유하며 읽기 전용입니다. 직접 작성하지 마십시오. aggrega plugin sync가 플러그인의 describe() 자기 보고에서 명령 표면을 읽어 여기에 기록하므로, CLI 플러그인이 설치하는 명령을 .wasm을 로드하지 않고도 엔티티에서 읽을 수 있습니다. cli가 아닌 플러그인은 명령을 제공하지 않으며 빈 목록을 기록합니다. 호스트는 정확히 이 집합을 설치합니다. 기록된 집합이 플러그인의 describe() 자기 보고와 다르면 로드 시 중단되며, 게시는 바이너리와 동기화되지 않은 집합을 거부하고 작성자에게 다시 기록하도록 안내합니다. 플러그인을 변경한 후 기록을 다시 동기화하려면 aggrega plugin sync를 실행하십시오.
각 명령 항목은 다음을 포함합니다.
| 필드 | 효과 |
|---|---|
name | 호스트가 등록하는 명령 동사입니다. 운영자가 호출하는 aggrega <name> 토큰이며, 호스트가 호출 시 플러그인에 전달하는 판별자이므로 여러 명령을 지원하는 단일 플러그인은 어떤 명령이 호출되었는지에 따라 라우팅할 수 있습니다. 각 항목에 필수입니다. |
description | 명령 목록과 도움말 출력에 표시되는 명령의 한 줄 짧은 도움말 텍스트입니다. 문서 용도일 뿐이며, 호스트는 이에 따라 동작하지 않습니다. |
flags | 선언된 순서대로 나열한 명령의 플래그입니다. 각 항목은 명령에 플래그 하나를 등록하므로 aggrega help <command>가 이를 핵심 명령의 플래그처럼 렌더링합니다. 플래그가 없는 명령은 이를 비워 둡니다. |
각 flags 항목은 플래그 하나를 선언합니다.
| 필드 | 효과 |
|---|---|
name | 플래그의 긴 이름, 즉 운영자가 명령줄에 전달하는 --name 토큰입니다. 각 항목에 필수입니다. |
shorthand | 플래그의 선택적 짧은 별칭, 즉 운영자가 긴 이름 대신 전달할 수 있는 -x 형태이며, 단일 ASCII 문자 또는 숫자입니다. 생략하면 플래그에 짧은 별칭이 없습니다. |
description | 명령의 도움말 출력에 표시되는 플래그의 한 줄 도움말 텍스트입니다. 선택적 문서이며, 호스트는 이를 검증하지도 않고 이에 따라 동작하지도 않습니다. |
type | 플래그의 값 타입(string, bool 또는 int)이며, 도움말이 렌더링하는 플래그의 종류입니다. 생략하면 문자열 플래그로 렌더링됩니다. |
default | 운영자가 플래그를 전달하지 않을 때의 기본값으로, 문자열로 표현합니다. bool 또는 int 플래그의 경우 해당 타입의 값입니다. 생략하면 플래그가 기본값을 선언하지 않습니다. |
CLI 플러그인은 describe()에서 명령과 그 플래그를 선언합니다. 호스트는 정확히 그 표면을 등록하고, 각 명령의 플래그를 내장 명령의 플래그와 같은 방식으로 aggrega help <command>에 렌더링합니다.
호스트는 플러그인의 명령을 추가할 때 플러그인이 선언한 모든 플래그를 검사하며, 선언이 실패한 플러그인은 추가되지 않고 건너뜁니다. 해당 플러그인의 명령은 하나도 등록되지 않고, 경고가 플러그인, 명령, 플래그와 그 문제점을 알려 주며, 내장 명령이든 다른 플러그인의 명령이든 그 밖의 모든 명령은 계속 동작합니다. 선언은 다음과 같은 경우 실패합니다.
- 플래그에 이름이 없거나, 한 명령이 같은 이름을 두 번 선언하는 경우
- shorthand가 단일 ASCII 문자 또는 숫자가 아니거나, 한 명령이 두 플래그에 같은 shorthand를 선언하는 경우
- 이름이나 shorthand가 모든
aggrega명령에 이미 있는 플래그(--help, 그-h, 그리고--offline,--config같은 전역 플래그)를 재사용하는 경우 - 타입이
string,bool,int중 하나가 아닌 경우 - 기본값이 플래그의 타입으로 파싱되지 않는 경우(
bool에 대한maybe,int에 대한three)
shorthand의 단일 문자 형태와 type의 세 가지 값은 이 엔티티의 스키마에도 포함되므로, 다른 값을 기록한 Plugin 엔티티는 카탈로그 로드 시 거부됩니다. 이름이나 shorthand가 명령마다 한 번만 나타나는지, 모든 명령에 있는 플래그를 재사용하지 않는지, 기본값이 해당 타입으로 파싱되는지는 호스트만 검사합니다. 이 검사는 호스트가 작성된 대로 도움말용 플래그를 선언할 수 있는지를 다루며, 플러그인이 자체 인수를 파싱하므로 플러그인이 선언한 플래그를 실제로 읽는지는 확인하지 않습니다.
metadata: pluginType: clispec: abiVersion: v1beta1 # commands is recorded by `aggrega plugin sync` from the plugin's describe() — do not author it. commands: - name: greet description: Print a friendly greeting flags: - name: name shorthand: n description: Who to greet type: string default: worldPlugin 검사하기
aggrega inspect <path-to-Plugin.yaml>는 Plugin 파일을 렌더링합니다. 렌더링하는 내용은 그 식별 정보와 소켓 유형, 그 블록이 선언하는 기능, 작성자 순서대로 나열한 export별 기능 표, 런타임 제약이며, --detail에서는 서명 포인터와 런타임 구성 키도 함께 렌더링합니다. Plugin은 파일 경로로 지정하거나, 카탈로그에 대한 <pluginType>/<name> 좌표로 지정할 수 있습니다. ../cli/aggrega-inspect.md를 참조하십시오.
상호 참조
- Wasm 플러그인 개발자 가이드 — 작성자의 전체 작업 흐름:
describe(), 기능 선언, 런타임 제한, 수명 주기, 서명, 버전 관리. - Wasm 플러그인 계약 — 플러그인이 연결되는 소켓 지점과 그 입력/출력 형태.
entities/featurerecipe.md— 엔터티 URI로 플러그인을 참조하는 FeatureRecipe의pipeline:인터페이스.cli/aggrega-lint.md—Plugin게시를 관할하는 게시 린터, 버전 증가 기준, 불변성 강제.