İçeriğe geç
AggregaAggrega
Dil seçin: Türkçe
Bu sayfa makine çevirisiyle çevrilmiştir. İngilizce orijinalini okuyun.

Plugin

Plugin, içerik adresli bir WebAssembly eklentisidir: sha256 özetiyle sabitlenmiş, OCI üzerinde barındırılan bir .wasm yapıtıdır ve uyguladığı soket türünü, hedeflediği ABI sürümünü, isteğe bağlı bir imza işaretçisini ve isteğe bağlı bir çalışma zamanı bloğunu bildirir. Bu varlık, bir eklentinin yazım ve meta veri yüzeyidir; bağımlılık çözümlemesi yapıtı özetiyle sabitler ve kayıt defterine özgü güven ilkesi, çekme sırasında imzasını doğrular. Derleyici eklentinin davranışını yorumlamaz; sabitlenmiş başvuruyu yönlendirir, baytları ise WebAssembly çalışma zamanı yürütür.

Bu sayfa, Plugin katalog yazım yüzeyini alan alan ele alır. Uçtan uca yazar iş akışı için (bir eklentinin ne olduğu, describe() öz bildirimi, yayımlama→çekme→derleme yaşam döngüsü, imzalama ve sürümleme) Wasm eklenti geliştirici kılavuzuna bakın. Bir eklentinin bağlandığı soket noktaları ve bunların girdi/çıktı biçimleri için Wasm eklenti sözleşmesine bakın.

Plugin’in rolü

Bir Plugin, mantıksal bir eklenti kimliğini somut bir .wasm yapıtına ve ana bilgisayarın onu güvenle yükleyip çalıştırmak için ihtiyaç duyduğu yetenek ve çalışma zamanı meta verilerine bağlar. Bir işlem hattı adımı ya da bir eklenti soketi, varlığa URI’si ile başvurur; varlık, bildirilen yetenekleri, çalışma zamanı sınırlarını ve imza işaretçisini taşırken çözümlenmiş içerik özeti release kilit dosyasında bulunur. .wasm konumu eklentinin kimliğinden türetilir — kendisi metadata.pluginType ile yalın metadata.name değerinden oluşturulan adreslenebilir koordinat plugin/<pluginType>/<name> ve yapılandırılmış kayıt defteri — ve yazılan bir alan değildir. Varlık üzerinden dolaylama zorunludur — yalın bir .wasm ya da yapıt başvurusu, onunla eşleşen bir varlık olmadığından yükleme sırasında reddedilir.

Bir Plugin’in bildirimleri soket türüne göre gruplanır ve varlığı okumak bu gruplamadan başlar:

  • Soket türü başına bir blok — spec.provider, spec.pipelineStep, spec.parser, spec.importer. Bir eklenti, metadata.pluginType alanının adlandırdığı tek bloğu taşır ve her blok, aggrega plugin gen-catalog tarafından eklentinin kendi describe() çıktısından kaydedilen ve anlamı yalnızca o bloğa ait olan bir capabilities: listesi içerir: bir sağlayıcının listesi sunduğu yetenekleri, bir işlem hattı adımınınki adımının uyumlu olduğu sağlayıcı yeteneklerini, bir ayrıştırıcınınki ve bir içe aktarıcınınki ise parse:<format> ve import:<format> biçiminde yazılan kaynak biçimlerini adlandırır. Anlamı taşıyan şey kapsamadır — bir yetenek girdisine, onun ne tür bir iddia olduğunu söyleyen blok okunmadan ulaşılamaz.
  • Bir sağlayıcı bloğu listesinden fazlasını taşır — spec.provider ayrıca eklentinin Workload türünü nasıl çevirdiğini, hangi platforma özgü ek açıklamaları okuduğunu ve render davranışı sözleşmesini (spec.provider.contract: girdi türleri, sınır birleştirme, yapıt ayırıcıları, örnek yeniden kullanımı) bildirir. Bunlar sunulan bir boyuttan çok render davranışını tanımlar; bu yüzden sağlayıcının yetenek listesinin içinde değil, yanında yer alırlar.
  • Kesişen bir soket hiçbir yetenek bildirmez — bir linter, governance ya da cli eklentisi dört bloğun hiçbirini taşımaz, çünkü hiçbir render boyutuna ve hiçbir kaynak biçimine hizmet etmez.
apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
name: aws-secrets-manager
version: 1.2.0
pluginType: pipeline-step
spec:
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 credential

metadata

Standart katalog meta verileri. name, version ve pluginType zorunludur; version katı bir Anlamsal Sürüm’dür (ör. 1.2.0). İsteğe bağlı alanlar — description, maintainers, license, repository, home, keywords — her katalog varlığının taşıdığı aynı biçimi izler ve metadata başka hiçbir anahtar kabul etmez. Yayımlanmış bir sürüm değiştirilemez: var olan bir sürümün yeniden yayımlanması yayımlama kapısında reddedilir.

metadata.name yalındır — hiçbir soket öneki taşımaz. Eklentinin adreslenebilir koordinatı plugin/<pluginType>/<name>, metadata.pluginType ve yalın metadata.name değerinden türetilir; ada yazılmaz.

metadata.pluginType

Bu eklentinin uyguladığı soket türü. Eklentinin kimliğinin bir parçası olduğu için adresleme bloğunda name ve version yanında yer alır: türetilen plugin/<pluginType>/<name> koordinatının <pluginType> bölümünü sağlar. Bir eklenti, çalışma zamanının tanıdığı eklenti türü sınıflandırmasından alınan tam olarak bir soket türünü uygular:

  • provider — IR düğümlerini sağlayıcıya özgü yapıtlara dönüştürür.
  • linter — yazılan içeriği inceler ve tanılamalar üretir.
  • pipeline-step — bir FeatureRecipe’in veya bir Recipe’in pipeline: alanında, işlenmiş belge kümesine yama uygulayan bir adım.
  • governance — derleme işlem hattının yönetişim rollerine hizmet eder. Topoloji oluşturma sırasında topoloji grafiği düğüm etiketlerini otomatik olarak etiketler ve ana bilgisayarın grafiğin yalnızca etiketlerden oluşan bir izdüşümüne uyguladığı JSON Patch belgeleri döndürür. Statik analiz veya işleme aşamasında IR grafiğini ya da işlenmiş yapıtları değerlendirir ve kabul/ret kararı döndürür; başarısız bir kural derlemeyi durdurur. Neler üretebileceğini türü değil, bağlandığı rol belirler.
  • parser — yabancı bir kaynak biçimini (HCL, TOML, YAML, JSON, …) yapılandırılmış bir JSON ağacına ayrıştırır; böylece derleyicinin yerel olarak ayrıştırmadığı bir biçimi okuması gereken bir tüketici ham metin yerine ayrıştırılmış bir ağaçla çalışır.
  • importer — yabancı bir altyapı veya ajan tanımı kaynağını taslak Aggrega yazma dosyalarına dönüştürür ve işlediği biçimleri import:<format> yetenekleri olarak duyurur.
  • cli — bir operatörün komut satırında çağırdığı bir çalışma zamanı aggrega <cmd> alt komutu ekler. Derleme zamanı işleme ve işlem hattı soketlerinden ayrı bir çalışma zamanı soketidir.

Zorunlu.

spec.abiVersion

Plugin’in hedeflediği host/guest ABI sürümü. Kabul edilen değer v1beta1’dir; yeni bir ABI revizyonu bir değer daha ekler. Zorunludur.

Yetenekleri bildirmek: soket türü başına bir blok

Yetenek, bir tüketicinin bir plugin’den istediği şeydir: bir Recipe’in talep ettiği bir işleme yeteneği ya da bir derlemenin okunmasını gerektirdiği bir kaynak biçimi. Bir plugin’in yetenekleri, kendi soket türüne ait bloğun içine kaydedilir; dolayısıyla listenin hangi blokta bulunduğu, girdilerinin ne anlama geldiğini belirler:

metadata.pluginTypeYeteneklerinin bildirildiği yerBir girdinin adlandırdığı şey
providerspec.provider.capabilitiesBu plugin’in sunduğu, helm veya compose gibi bir işleme yeteneği.
pipeline-stepspec.pipelineStep.capabilitiesBu plugin’in adımının, işlenmiş çıktısıyla uyumlu olduğu bir sağlayıcı.
parserspec.parser.capabilitiesBu plugin’in okuduğu, parse:<format> biçiminde yazılan bir kaynak biçimi.
importerspec.importer.capabilitiesBu plugin’in varlık taslakları çıkardığı, import:<format> biçiminde yazılan yabancı bir kaynak biçimi.
linter, governance, cli—Hiçbir şey. Bu soketler hiçbir yetenek sunmaz, bu nedenle dört bloğun hiçbirini taşımazlar.

Bir eklenti tam olarak bir soket türü uygular; bu yüzden varlığı tek bir blok taşır. Liste, eklentinin kendi bildirimidir: aggrega plugin gen-catalog, eklentinin describe() çıktısını okur ve bildirdiği her yeteneği bloğa yazar. Yazar, yayımlamadan önce listeyi daraltarak eklentinin bildirdiği ama yayımlanan varlığın sunmaması gereken bir yeteneği dışarıda bırakabilir; aggrega validate <entity> --plugin <file.wasm> ve aggrega push daraltılmış bir listeyi kabul eder ve eklentinin bildirip listenin dışarıda bıraktığı her yeteneği adlandıran bir bildirim yazdırır. Hiçbiri, eklentinin bildirmediği bir yeteneği adlandıran bir listeyi kabul etmez: ikisi de böyle bir listeyi, her bir yeteneği ve eklentinin bildirdiği yetenekleri adlandırarak reddeder; böylece yayımlanan bir liste hiçbir zaman eklentinin sağladığından fazlasını sunmaz. Eklentisi helm ve helm-chart bildiren ama compose’u da listeleyen bir pipeline-step varlığı şöyle reddedilir:

[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()

Bir tüketici tam olarak listelenen şeye göre çözümler.

spec.provider

Bir pluginType: provider eklentisi için provider soketi bloğu: sunduğu yetenekler, platformun sahip olduğu aggrega.ai/v1beta1 Workload türünü nasıl çevirdiği, hangi platforma özgü açıklamaları okuduğu ve render davranışı sözleşmesi. Blok, provider render eden her eklentide bulunur ve diğer her eklenti türünde bulunmaz. Workload sentezi olmadan yalnızca kaynaklı veya artifact içeriği render eden bir provider da bloğu taşır — yeteneklerini ve sözleşmesini orada bildirir ve yalnızca workloadSchema alanını atlar.

spec.provider.capabilities

Bu provider’ın sunduğu ve çıktı biçimini render ettiği yetenekler — helm veya compose gibi yetenek adları. Bir provider tüm yetenekler genelinde değil, bir yeteneğin çıktı biçimini paylaşan artifact’ler genelinde geneldir; bu nedenle liste, eklentinin kendisinin bildirdiği yetenekleri adlandırır: aggrega plugin gen-catalog onu eklentinin describe() çıktısından kaydeder ve yazar yayımlamadan önce onu daraltabilir. Girdiler kaydedildikleri sırayı korur.

Bir Recipe’in istediği provider hedefi (spec.capability: helm), listesi bu hedefi içeren provider eklentisine çözümlenir. Birden fazla provider eklentisi aynı hedefi listelediğinde seçimi çalışma alanı yapar: çalışma alanı yapılandırmasındaki plugins.providers seçimi hangi eklentinin kullanılacağını belirtir; bu seçim aggrega pull sırasında çözümlenir ve kilit dosyasına kaydedilir. Seçim yoksa ve tam olarak bir aday varsa o aday kullanılır; seçim yoksa ve birden fazla aday varsa derleme durur ve her adayı adıyla belirtir. Belirsizlik, katalog genelinde bir benzersizlik kuralıyla değil, kullanım noktasında çalışma alanı başına çözülür. Boş veya bulunmayan bir liste hiçbir yetenek iddiası bildirmez; dolayısıyla eklenti hiçbir hedefe hizmet etmez.

Buradaki bir yetenek adı iki nokta üst üste içermez. Bir Recipe’in spec.capability değeri, son iki noktaya kadar olan kısım yetenek, sonrası ise sürüm sabitlemesi olarak okunur; bu nedenle iki nokta içeren bir ad hiçbir zaman istenemez. describe() çağrısı böyle bir ad bildiren eklenti yüklenirken reddedilir ve ondan yayımlama için hiçbir varlık üretilmez. Aynı durum bir pipeline-step eklentisinin listelediği provider yetenekleri için de geçerlidir. Bir ayrıştırıcının parse:<format> ve bir içe aktarıcının import:<format> adlarındaki iki nokta bu adların parçasıdır ve kalır.

spec.provider.workloadSchema

Bu provider’ın aggrega.ai/v1beta1 Workload türünü provider’a özgü manifest’lere nasıl çevirdiğini belgeleyen bir JSON Schema 2020-12 bildirimi. Sentez yapan bir provider’da uzlaşım gereği bildirilir: böyle bir provider workloadSchema alanını belgelenmiş çeviri sözleşmesi olarak bildirir; provider’ın hangi Workload alanlarını tükettiğini, enum biçimli her alanın hangi kapalı kümeleri kabul ettiğini ve hangi aralık kısıtlamalarının uygulandığını açıklar.

Gövde, Plugin yüklenirken JSON Schema 2020-12’ye derlenir — hatalı bir şemayı render sırasında değil yükleme sırasında reddeden yapısal bir koruma. Bir workload: Recipe’inin desteklenip desteklenmediğini bu alanın varlığı değil, bağlı provider’ın sentez yeteneği belirler: sentez yapamayan bir provider’a bağlanmış sentezlenmiş kipteki bir Recipe, render sırasında açıkça durur. Standart kütüphane kataloğu workloadSchema alanını provider yeteneğiyle uyumlu tutar. Alan belgelenmiş sözleşmedir; başka hiçbir şey onu okumaz. Workload gövdelerinin kendisi bu provider başına alana karşı değil, platformun sahip olduğu gömülü Workload şemasına karşı doğrulanır.

spec.provider.wellKnownAnnotations

Bu provider’ın okuduğu platforma özgü, iyi bilinen açıklama anahtarlarını — ayrılmış aggrega.ai/ ad alanı altındakileri — her biri bulunmadığında uygulanan davranışla birlikte sıralayan sıralı bir dizi. Her girdi bir key (provider’ın okuduğu açıklama, ör. aggrega.ai/namespace), bir purpose (açıklama bulunduğunda neyi denetlediği), isteğe bağlı bir defaultBehavior (açıklama bulunmadığında provider’ın ne yaptığı) ve provider’ın anahtarı nerede okuduğunu listeleyen isteğe bağlı bir scope taşır — Recipe girdi türleri olan sourced, synthesized veya artifactsStandalone, ya da sınır başına bir kez okunan bir anahtar için boundary. key ve purpose zorunludur; girdiler yazarın sırasını korur.

Alan, provider’ın destek beyanıdır ve derleyici onu iki şekilde okur. scope değeri, bloğun kendi contract.inputKinds alanının iddia etmediği bir girdi türünü adlandıran bir girdi bu iddiayla çelişir ve Plugin, anahtarı ve kapsamı adlandırarak reddedilir. Ayrıca bir derleme bu provider üzerinden işlendiğinde, işlemenin bildirdiği hiçbir girdi türünde hiçbir girdinin kapsamadığı bir aggrega.ai/ açıklaması, anahtarı, provider’ı ve bu girdi türlerini adlandıran bir uyarıya yol açar; değer yine de dokunulmadan geçer ve derleme durmaz. Alan yoksa hiçbir beyanda bulunmaz ve bu provider için böyle bir uyarı üretilmez. Şema doğrulaması yalnızca her girdinin biçimini denetler (anahtar aggrega.ai/ ad alanı altındadır, purpose mevcuttur); bu, ayrılmış ad alanına bir değer bağlamayı yöneten çalışma zamanı denetiminden ayrıdır.

metadata:
pluginType: provider
spec:
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.

Standart kütüphane provider’larının sağladığı provider başına açıklama kümeleri ve workloadSchema içeriği ../providers/well-known-annotations.md, ../providers/helm.md, ../providers/helm-chart.md ve ../providers/compose.md sayfalarında belgelenmiştir.

spec.provider.readsNoWellKnownAnnotations

Bu provider’ın platforma özgü iyi bilinen açıklama anahtarlarından hiçbirini okumadığını bildirir. Hiçbir anahtarı kapsamayan bir destek beyanıdır ve hem bunu hem de wellKnownAnnotations alanını dışarıda bırakmanın söylemediği bir şeyi söyler: bulunmayan bir beyan sessizliktir, bu ise provider’ın ayrılmış aggrega.ai/ ad alanı altında hiçbir şey okumadığına dair kendi ifadesidir. Böyle bir provider üzerinden işlenen bir derleme, işlemeye ulaşan her aggrega.ai/ açıklaması için anahtarı, provider’ı ve işlemenin bildirdiği girdi türlerini adlandırarak uyarır; değer yine de dokunulmadan geçer ve derleme durmaz.

Yalnızca true yazılabilir; bu nedenle alanı dışarıda bırakmak hiçbir şey söylememenin tek yolu olarak kalır. wellKnownAnnotations ile birlikte yazılamaz: anahtarların bazılarını okuyan bir provider bunun yerine onları orada listeler. Her iki ret de şema düzeyindedir; bu nedenle Plugin okunduğunda reddedilir.

spec:
provider:
capabilities:
- terraform
readsNoWellKnownAnnotations: true

Standart kütüphanedeki terraform provider’ı bunu bildirir; bunun, onun üzerinden işlenen bir Release için ne anlama geldiğini ../providers/terraform.md açıklar.

spec.provider.contract

Provider oluşturan bir plugin’in kendi beyan ettiği derleme zamanı oluşturma davranışı sözleşmesi: oluşturduğu girdi türleri, bir dağıtım grubunun düğüm başına çıktısını nasıl birleştirdiği, içe aktarılan artifact dosyalarına uyguladığı şablon sınırlayıcı çifti, yüklenmiş tek bir örneğin her geçişe hizmet edip edemeyeceği, omit girdilerini dikkate alıp almadığı ve bir Recipe’in kendi sınırının paylaşılan çıktısına kattığı dosyaları kabul edip etmediği. Aynı blokta capabilities alanının yanında yer alır, ancak farklı bir soruyu yanıtlar: yetenek listesi bu plugin’in hangi yeteneklere hizmet ettiğini söylerken, sözleşme bunları nasıl oluşturduğunu söyler. aggrega plugin gen-catalog bunu plugin’in kendi describe() öz bildiriminden kaydeder ve ana makine yayımlama ve yükleme sırasında bunu o öz bildirimle çapraz denetler; bir uyuşmazlık derlemeyi durdurur. Bulunmaması hiçbir oluşturma davranışı sözleşmesi beyan etmez ve çapraz denetim yalnızca export başına beyanları karşılaştırır. Tüm alanlar isteğe bağlıdır.

AlanEtki
inputKindsPlugin’in üç Recipe girdi türünden hangilerini oluşturduğu; her biri bağımsız bir boolean beyandır: sourced (kaynaklı bir dosya kümesi — bir chart, bir modül, bir compose dosyası), synthesized (sentezlenmiş bir Workload) ve artifactsStandalone (içe aktarılmış artifact belgeleri taşıyan, kaynağı ya da workload’u olmayan bağımsız bir düğüm). Ana makine bir düğümün girdi türünü bu kümeye göre denetler.
boundaryAssemblyPlugin’in bir dağıtım grubunun düğüm başına oluşturma çıktısını nasıl birleştirdiği: none her düğümün çıktısını doğrudan dağıtım yoluna yazar; merge düğüm başına parçaları tek bir belgede birleştirir; nest her düğümün çıktısını bir şemsiye yapı içinde kendi konumuna yerleştirir. Bulunmaması hiçbir birleştirme beyanı taşımaz.
artifactDelimitersPlugin’in içe aktarılan artifact dosyalarına uyguladığı Go şablonu sınırlayıcı çifti; left ve right olarak. Bulunmaması varsayılan {{/}} çifti anlamına gelir; hedef sözdizimi bu çiftle çakışan bir plugin alternatif bir çift beyan eder (örneğin [[/]]).
reusableInstanceYüklenmiş tek bir plugin örneğinin, her geçiş için yeni bir örnek yerine bir derlemenin tüm oluşturma, birleştirme ve doğrulama geçişlerine hizmet edip edemeyeceği. Yalnızca plugin geçişler arasında durum tutmadığında true olarak beyan edilir; böylece tek bir örnek, yeniden kullanılsa da yeni yüklense de bayt bayt aynı çıktıyı üretir. Bulunmaması (false) her geçiş için yeni bir örnek yükler ve doğası gereği durum taşıyan bir plugin’i yalıtır. aggrega build --verify-determinism, her düğümü iki kez oluşturup herhangi bir farkta durarak yeniden kullanılabilir bir plugin’in çıktısının kararlı olduğunu kanıtlar.
omitsPlugin’in omit girdilerini — bir düğümün çıktısından dışarıda bırakılacak oluşturulmuş birimleri adlandıran girdileri — dikkate alıp almadığı: bir girdinin eşleştiği her birimi oluşturduğu çıktının dışında bırakır ve her girdinin kaç birimle eşleştiğini bildirir. Değer, plugin’in describe() çağrısının bildirdiği beyanı kaydeder; bu nedenle true yalnızca bunu bildiren bir plugin için doğrudur ve bildirimden farklı bir değer derlemeyi durdurur. Bulunmaması (false) böyle bir destek beyan etmez.
boundaryArtifactsPlugin’in hedefinin, bir Recipe’in içinde oluşturulduğu sınırın paylaşılan çıktısına Recipe’in spec.boundary.artifacts altında kattığı dosyaları kabul edip etmediği: derleyici bu tür her dosyayı, plugin’in sınır için birleştirdiği içeriğin yanına bir kez yazar ve hedef onu o çıktının parçası olarak okur. Değer, plugin’in describe() çağrısının bildirdiği beyanı kaydeder ve bildirimden farklı bir değer derlemeyi durdurur. Bulunmaması (false) böyle bir destek beyan etmez ve bu plugin için bloğu beyan eden bir Recipe, herhangi bir şey oluşturulmadan önce reddedilir.
metadata:
pluginType: provider
spec:
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: true

spec.pipelineStep

Bir pluginType: pipeline-step eklentisi için işlem hattı adımı bloğu. Tek alanı olan capabilities, eklentinin adımının işlenmiş çıktısını nasıl dönüştüreceğini bildiği sağlayıcıları adlandırır: helm veya compose gibi yetenek adları. Bir adım her seferinde tek bir sağlayıcının çıktı biçimine göre yazılır; bu nedenle liste, eklentinin kendisinin bildirdiği sağlayıcıları adlandırır; girdiler kaydedildikleri sırayı korur. Blok yalnızca işlem hattı adımı eklentilerinde bulunur.

Blok, bu iddianın katalogdan okunabilen kaydıdır: aggrega plugin gen-catalog onu eklentinin kendi describe() öz bildiriminden kaydeder ve yazar yayımlamadan önce onu daraltabilir. Denetim aynı iddiayı eklentiden okur: bir adım bir kapsama dokunduğunda, o kapsamın belgelerini işleyen sağlayıcı eklentinin iddia ettikleri arasında değilse derleme durur. Boş veya bulunmayan bir liste hiçbir uyumluluk iddiası bildirmez; dolayısıyla hiçbir kapsam adımı kabul etmez.

metadata:
pluginType: pipeline-step
spec:
abiVersion: v1beta1
pipelineStep:
capabilities: # recorded by `aggrega plugin gen-catalog` from describe()
- helm
- compose

spec.parser

pluginType: parser türündeki bir plugin için ayrıştırıcı bloğu. Tek alanı olan capabilities, plugin’in kanonik yapılandırılmış bir ağaca dönüştürdüğü kaynak biçimlerini adlandırır; her biri parse:<format> olarak yazılır. Önek girdinin bir parçasıdır; bu nedenle birden çok biçim okuyan bir plugin her biçim için bir girdi listeler. aggrega plugin gen-catalog listeyi plugin’in kendi describe() çıktısından kaydeder, yazar yayımlamadan önce onu daraltabilir ve girdiler kaydedildikleri sırayı korur. Blok yalnızca ayrıştırıcı plugin’lerde bulunur.

İstenen bir biçim, listesinde eşleşen girdiyi içeren ayrıştırıcıya çözümlenir. Hiçbir ayrıştırıcının bildirmediği bir biçim derlemeyi durdurur; birden fazla ayrıştırıcı plugin tarafından bildirilen bir biçim ise adayları adlandırarak belirsiz olarak durdurur. Geri dönüş yoktur, çünkü bir ayrıştırıcının geri dönülecek sıfır yapılandırmalı bir varsayılanı yoktur. Boş ya da hiç olmayan bir liste hiçbir biçim iddiası bildirmez; bu nedenle plugin hiçbir şeyi ayrıştırmaz.

metadata:
pluginType: parser
spec:
abiVersion: v1beta1
parser:
capabilities: # recorded by `aggrega plugin gen-catalog` from describe()
- parse:hcl
- parse:toml

spec.importer

Bir pluginType: importer eklentisinin importer bloğu. capabilities alanı, eklentinin taslak Aggrega yazım dosyalarına dönüştürdüğü yabancı kaynak biçimlerini adlandırır; her biri import:<format> olarak yazılır. Önek girdinin bir parçasıdır; bu nedenle birkaç biçimi işleyen bir eklenti her biçim için bir girdi listeler. aggrega plugin gen-catalog listeyi eklentinin kendi describe() çıktısından kaydeder, yazar yayımlamadan önce onu daraltabilir ve girdiler kaydedildikleri sırayı korur. Blok yalnızca importer eklentilerinde bulunur.

İstenen bir içe aktarma biçimi, listesinde eşleşen girdiyi içeren importer’a çözümlenir. Hiçbir importer’ın bildirmediği bir biçim içe aktarmayı durdurur; birden fazla importer eklentisinin bildirdiği bir biçim ise adayları adlandırarak belirsiz olarak durur, meğer ki çalışma alanı yapılandırmasındaki bir plugins.importer girdisi bunlardan birini bağlasın; bu durumda çalışan o olur. Boş ya da bulunmayan bir liste hiçbir biçim iddiası bildirmez; dolayısıyla eklenti hiçbir şeyi içe aktarmaz.

detect alanı, bir içe aktarma hiçbir biçim adlandırmadığında bu biçimlerdeki bir kaynağın tanındığı imzaları kaydeder. Host fonksiyonu ve komut kayıtları gibi makineye aittir: varlık eklentiden üretildiğinde eklentinin describe() çıktısında bildirdiklerinden, eklentinin imzaları bildirdiği sırayla türetilir ve yazar tarafından yazılmaz. Her imza şunları adlandırır:

  • syntax — kaynağın ayrıştırıldığı sözdizimsel biçim; bir parser eklentisinin parse:<syntax> olarak bildirdiği biçim, örneğin json ya da yaml.
  • files — kaynağın adının sonuna karşı eşleştirilen isteğe bağlı dosya adı kalıpları: tek segmentli bir kalıp dosyanın kendi adına, eğik çizgiyle ayrılmış birkaç segmentli bir kalıp ise yolunun sondaki aynı sayıda segmentine karşı eşleştirilir; böylece .vscode/mcp.json, .vscode adlı bir dizindeki mcp.json adlı bir dosyayla eşleşir. *, ? ve [...] bir segment içinde eşleşir. Bulunmadığında imza, adı ne olursa olsun tek dosyadan oluşan bir kaynağa uygulanır ve bir dizinin hiçbir dosyasına uygulanmaz. Bir importer’ın imzalarının kalıpları, aggrega import komutunun ona bir dizinin hangi dosyalarını vereceğini de belirler.
  • match — ayrıştırılmış ağacın sağlaması gereken yüklemler, hepsi birden. Her birinin bir path değeri, yani ağacın tepesinden noktalarla birleştirilmiş anahtarlar (tam sayı bir segment bir dizi konumunu seçer); bir is değeri, yani present, absent, object, array, string, number ve boolean değerlerinden biri; ve isteğe bağlı olarak değerin tam olarak eşit olması gereken bir dize olan equals ya da değerin başlaması gereken bir dize olan prefix vardır — ikisinden en fazla biri.

Bir içe aktarma hiçbir biçim adlandırmadığında, çalışma alanının kataloğunun tuttuğu her importer’ın — tüm sürümler dahil — ve derleyicinin çekirdek importer’larının imzaları kaynağa karşı eşleştirilir. Kaynak, adına uygulanan bir imzanın onu okuduğu her sözdizimi için bir kez, çalışma alanının kataloğunun o sözdizimi için sunduğu parser aracılığıyla — ya da kataloğun parser sunmadığı bir sözdizimi için derleyicinin kendi taşıdığı parser aracılığıyla — ayrıştırılır ve bir sözdiziminde ayrıştırılamayan bir kaynak o sözdizimini adlandıran hiçbir imzayla eşleşmez. Bir dizin, dosyaları üzerinden eşleştirilir: her imza, kalıplarının seçtiği dizin dosyalarına ad sırasıyla denenir ve hiçbir kalıp bildirmeyen bir imza bunların hiçbirine uygulanmaz. Bir imzanın eşleştiği kaynak, importer’ının bildirdiği her biçim olarak tanınır. Tanınan tek bir biçim varsa kaynak o biçimde okunur. Hiçbir imzanın eşleşmediği bir kaynak, biçimi sorarak ve importer’ların bildirdiği biçimleri adlandırarak — ya da bir dizin için, dosyalarından birini tek başına ya da importer’ı dosya kalıpları bildiren bir biçimi sorarak ve yalnızca bu biçimleri adlandırarak — reddedilir; birden fazla biçim olarak tanınan bir kaynak ise bunları adlandırarak More than one importer recognises the source (Kaynağı birden fazla importer tanıyor) koşuluyla reddedilir. Dolayısıyla birden fazla biçim bildiren bir importer’ın imzalarının eşleştiği her kaynak belirsiz olarak reddedilir; kaynaklarının tanınması istenen bir importer tek bir biçim sunar.

Varlık detect kaydettiğinde, bu kayıt eklentinin describe() çıktısında bildirdiğine imza imza ve sırasıyla eşit olmalıdır: importer yüklenirken, bildirimi farklı olan bir eklenti importer.detect adlandırılarak reddedilir; yayımlama da aynısını yapar. Hiçbir detect kaydetmeyen bir varlık hiçbir iddiada bulunmaz ve karşılaştırılmaz; dolayısıyla eklentisinin describe() çıktısı hangi imzaları bildirirse onları yükler ve importer’ının biçimlerine o zaman yalnızca adları verilerek ulaşılır.

metadata:
pluginType: importer
spec:
abiVersion: v1beta1
importer:
capabilities: # recorded by `aggrega plugin gen-catalog` from describe()
- import:langflow
detect:
- syntax: json
match:
- path: data.nodes
is: array

spec.signature

Plugin’e eklenmiş imzayı gösteren isteğe bağlı, açıklayıcı bir işaretçi. Bu blok yalnızca belgeleme amaçlıdır: katalog okuyucuları için imzanın nerede bulunduğunu ve nasıl üretildiğini kaydeder; plugin’i kendisi kabul etmez. Zorlayıcı denetim, çekme sırasında uygulanan kayıt defterine özgü güven ilkesidir: imza bir OCI referrer olarak getirilir, kayıt defterinin güvenilen kimliklerine ya da sabitlenmiş anahtarına karşı doğrulanır ve lockfile’a doğrulanmış bir olgu olarak kaydedilir. İmza gerektiren bir kayıt defteri, gerekli bir imza eksik, güvenilmeyen ya da geçersiz olduğunda çekmeyi durdurur.

  • type — imza şeması. Desteklenen şema sigstore-cosign’dur. Blok mevcut olduğunda zorunludur.
  • signatureRef — eklenmiş imza paketinin belgeleme ve keşif amaçlı OCI referrer başvurusu. İmza burada sabitlenmek yerine çekme sırasında referrer listelemesiyle keşfedildiğinde bulunmaz.
  • publicKeyRef — anahtarlı bir imza için, imzanın üretildiği açık anahtarı gösteren bir işaretçi. Bulunmaması, kayıt defterinin güvenilen kimliklerine karşı doğrulanan anahtarsız (OIDC kimlikli) bir imzayı belirtir.

spec.runtime

Host’un plugin’i yüklerken ve çalıştırırken uyguladığı isteğe bağlı yürütme kısıtlamaları. Dışa giden ağ erişimi bir yazım alanı değildir: bir plugin derleme zamanında ağa asla erişmez — derleme öncesi (ahead-of-time) sınır budur — bu nedenle burada bir host izin listesi alanı yoktur. Bir plugin’in ihtiyaç duyduğu uzak içerik, ortam ağ erişimi yoluyla değil, her zaman Release’in lockfile’ında kaydedilen, host aracılığıyla sağlanan ve digest ile sabitlenmiş harici girdi kanalı üzerinden gelir; geliştirici kılavuzu fetch sarmalayıcısını ve sabitleme disiplinini belgeler.

AlanEtki
maxMemoryPagesPlugin’in doğrusal belleğini Wasm sayfası cinsinden sınırlar (sayfa başına 64 KiB). Sıfır ya da belirtilmemiş olması platformun varsayılan sınırını uygular, böylece bir yükleme hiçbir zaman sınırsız olmaz; daha fazlasına ihtiyaç duyan bir ek bu değeri yükseltir.
timeoutMsPlugin’in kendi kodunun tek bir çağrı sırasında ne kadar süre çalışabileceğini milisaniye cinsinden sınırlar; çağırdığı host fonksiyonlarının içinde geçen süre buna dahil değildir. Linux’ta ölçü işlemci süresidir, bu nedenle yoğun bir makinede işlemci beklerken geçen süre sayılmaz; diğer sistemlerde geçen gerçek süredir. Yeni yüklenmiş bir plugin’e yapılan ilk çağrı, plugin’in kendi başlatılmasını da sayar. Sıfır ya da belirtilmemiş olması platformun varsayılan sınırını uygular, böylece bir çağrı hiçbir zaman iptal edilemez olmaz; daha uzun çalışan bir ek bu değeri yükseltir.
hostFunctionsPlugin’in içe aktardığı host fonksiyonlarının adları. Makine tarafından türetilir ve salt okunurdur — elle yazmayın: aggrega plugin sync host fonksiyonlarını .wasm içe aktarma bölümünden okur ve bu alanı kaydeder, publish ikili dosyadan farklı bir kaydı reddeder; değer yayımlanan ikili dosyayı yansıtır ve özenle seçilmiş izin listesine göre doğrulanır. Host tam olarak bu kümeyi kaydeder ve her plugin’e ikili dosyasının ihtiyaç duyduğu en az ayrıcalıklı host yüzeyini verir; pull, damgayı yeniden türetir ve ikili dosyaya göre doğrular. Değeri yayımlamadan önce önizlemek için aggrega inspect --plugin <file.wasm> komutunu çalıştırın.
configKVÇalışma zamanının başlangıçta plugin’e verdiği, Plugin’e özgü yapılandırma; dizeden dizeye anahtar/değer çiftleri olarak. Girdiler yazarın sırasını korur, böylece üretilen kayıt çalıştırmalar arasında bayt bayt aynı olur. Bulunmaması, çalışma zamanının varsayılan boş yapılandırmasını geçerli bırakır.

spec.exports

Eklentinin sunduğu dışa aktarımlar; her biri bildirilmiş yeteneğiyle birlikte, yazarın sırasını koruyan sıralı bir liste olarak verilir. Bir dışa aktarım, ana makinenin çağrıyı yönlendirdiği adlandırılmış bir giriş noktasıdır (örneğin render_node, lint_naming, step); dışa aktarım başına yetenek bloğu, aggrega plugin gen-catalog aracının eklentinin describe() öz bildiriminden kaydettiği biçimiyle o dışa aktarımın ne yaptığını belirtir ve ana makine bunu yayımlama ve yükleme sırasında o öz bildirimle karşılaştırarak denetler. Bulunmaması, yazılmış bir dışa aktarım yüzeyi bildirmez.

AlanEtki
nameDışa aktarımın ABI adı — ana makinenin çağrıyı yönlendirdiği ad. Her girdi için zorunludur.
operatesDışa aktarımın gerçekleştirdiği işlem hattı işlemi: patch (var olan, işlenmiş bir belgeyi değiştirir) veya emit (yeni bir belge ekler). Ana makine değeri eklentinin öz bildirimiyle karşılaştırarak denetler; bu, doğrulanan bir yetenek beyanıdır, bir yönlendirme anahtarı değildir — bir adımın gerçekleştirdiği işlemi konuğun döndürdüğü sonuç taşır. Bulunmaması, herhangi bir işlem beyanı taşımaz.
scopeDışa aktarımın üzerinde çalıştığı belge kökü: own (düğümün kendi işlenmiş belgeleri) veya host (bileşen kapsamlı bir FeatureRecipe’in eklendiği bileşenin belgeleri). Ana makine, sağlayıcı uyumluluğunu o kapsamı işleyen sağlayıcıya karşı zorlamak için bildirilen kapsamı adımdan önce okur. Bulunmaması durumunda varsayılan own olur.
selectorDışa aktarımın neye etki ettiğini anlatan, serbest biçimli, insanlar tarafından okunabilir bir açıklama (örneğin workloads carrying a pod template). Katalog okuyucuları ve inceleme yüzeyi için belgelemedir; derleyici bunu yorumlamaz.

spec.commands

Bir cli eklentisinin katkıda bulunduğu üst düzey aggrega <command> fiilleri; eklentinin describe() öz bildiriminin bildirdiği sırayı koruyan sıralı bir liste olarak verilir. Makineye aittir ve salt okunurdur — bunu yazmayın. aggrega plugin sync, komut yüzeyini eklentinin describe() öz bildiriminden okur ve buraya kaydeder; böylece bir CLI eklentisinin kurduğu komutlar .wasm yüklenmeden varlıktan okunabilir. cli olmayan bir eklenti hiçbir komut katkısında bulunmaz ve boş bir liste kaydeder. Ana makine tam olarak bu kümeyi kurar; eklentinin describe() öz bildiriminden ayrışan kayıtlı bir küme yükleme sırasında durur ve yayımlama, ikili dosyayla eşzamanlı olmayan bir kümeyi reddederek yazarı kümeyi yeniden kaydetmeye yönlendirir. Eklentiyi değiştirdikten sonra kaydı yeniden eşzamanlamak için aggrega plugin sync komutunu çalıştırın.

Her komut girdisi şunları taşır:

AlanEtki
nameAna makinenin kaydettiği komut fiili — bir operatörün çağırdığı aggrega <name> belirteci ve ana makinenin çağrı sırasında eklentiye verdiği ayırt edici; böylece birkaç komutu destekleyen tek bir eklenti, hangi komutun çağrıldığına göre yönlendirme yapar. Her girdi için zorunludur.
descriptionKomutun komut listesinde ve yardım çıktısında gösterilen tek satırlık kısa yardım metni. Yalnızca belgelemedir; ana makine buna göre işlem yapmaz.
flagsKomutun bayrakları, bildirildikleri sırayla. Her girdi komuta bir bayrak kaydeder; böylece aggrega help <command> bu bayrağı bir çekirdek komutun bayrağı gibi işler. Bayrağı olmayan bir komut bunu boş bırakır.

Her flags girdisi bir bayrak bildirir:

AlanEtki
nameBayrağın uzun adı — bir operatörün komut satırında verdiği --name belirteci. Her girdi için zorunludur.
shorthandBayrağın isteğe bağlı kısa takma adı — bir operatörün uzun ad yerine verebileceği -x biçimi — tek bir ASCII harf veya rakam olarak. Bulunmaması, bayrağın kısa takma adı olmadığı anlamına gelir.
descriptionBayrağın komutun yardım çıktısında gösterilen tek satırlık yardım metni. İsteğe bağlı belgelemedir; ana makine bunu ne doğrular ne de buna göre işlem yapar.
typeBayrağın değer türü — string, bool veya int — ve yardımın onu hangi tür bayrak olarak işlediği. Bulunmaması durumunda bir dize bayrağı olarak işlenir.
defaultOperatör bayrağı vermediğinde bayrağın varsayılan değeri, bir dize olarak ifade edilir. Bir bool veya int bayrağı için bu, o türden bir değerdir. Bulunmaması, bayrağın varsayılan bildirmediği anlamına gelir.

Bir CLI eklentisi komutlarını ve bayraklarını describe() içinde bildirir; ana makine tam olarak bu yüzeyi kaydeder ve her komutun bayraklarını aggrega help <command> içinde yerleşik bir komutun bayraklarını işlediği şekilde işler.

Ana makine, eklentinin komutlarını eklerken eklentinin bildirdiği her bayrağı denetler ve bildirimleri başarısız olan bir eklenti eklenmek yerine atlanır: komutlarının hiçbiri kaydedilmez, bir uyarı eklentiyi, komutu, bayrağı ve bayraktaki sorunu belirtir ve diğer tüm komutlar — yerleşik olanlar veya başka bir eklentiden gelenler — çalışmaya devam eder. Bir bildirim şu durumlarda başarısız olur:

  • bir bayrağın adı yoksa veya bir komut aynı adı iki kez bildiriyorsa;
  • bir kısaltma tek bir ASCII harf veya rakamdan başka bir şeyse veya bir komut iki bayrak için aynı kısaltmayı bildiriyorsa;
  • bir ad veya kısaltma, her aggrega komutunda zaten bulunan bir bayrağı yeniden kullanıyorsa — --help, onun -h biçimi ve --offline ile --config gibi genel bayraklar;
  • bir tür string, bool veya int dışında bir şeyse;
  • bir varsayılan, bayrağın türü olarak ayrıştırılamıyorsa — bir bool için maybe, bir int için three.

shorthand alanının tek karakterli biçimi ve type alanının üç değeri de bu varlığın şemasının parçasıdır; bu nedenle başka bir değer kaydeden bir Plugin varlığı katalog yüklenirken reddedilir. Bir ad veya kısaltmanın komut başına bir kez geçmesi, hiçbirinin her komutta bulunan bir bayrağı yeniden kullanmaması ve bir varsayılanın kendi türü olarak ayrıştırılması yalnızca ana makine tarafından denetlenir. Denetim, ana makinenin bir bayrağı yardım için yazıldığı haliyle bildirip bildiremeyeceğini kapsar; eklentinin bildirdiği bayrakları okuyup okumadığını görmez, çünkü eklenti kendi bağımsız değişkenlerini kendisi ayrıştırır.

metadata:
pluginType: cli
spec:
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: world

Bir Plugin’i incelemek

aggrega inspect <path-to-Plugin.yaml> bir Plugin dosyasını görüntüler: kimliğini ve soket türünü, bloğunun bildirdiği yetenekleri, yazarın verdiği sırayla dışa aktarım başına yetenek tablosunu, çalışma zamanı kısıtlamalarını ve --detail düzeyinde imza işaretçisini ve çalışma zamanı yapılandırma anahtarlarını. Bir Plugin dosya yoluyla ya da kataloğa göre <pluginType>/<name> koordinatıyla adreslenebilir. Bkz. ../cli/aggrega-inspect.md.

Çapraz başvurular

  • Wasm plugin geliştirici kılavuzu — uçtan uca yazar iş akışı: describe(), yetenek bildirimleri, çalışma zamanı sınırları, yaşam döngüsü, imzalama, sürümleme.
  • Wasm plugin sözleşmesi — bir plugin’in bağlandığı soket noktaları ve bunların girdi/çıktı biçimleri.
  • entities/featurerecipe.md — bir plugin’e varlık URI’si ile başvuran FeatureRecipe pipeline: yüzeyi.
  • cli/aggrega-lint.md — bir Plugin’in yayımlanmasını yöneten yayımlama denetleyicisi, sürüm artırma ölçütleri ve değiştirilemezlik denetimi.