Wasm eklenti geliştirici kılavuzu
Bu, bir Aggrega WebAssembly (Wasm) eklentisi yazmaya ve onu bir katalog varlığı olarak yayımlamaya yönelik temel kılavuzdur. Eklenti yazarının sözleşmesini baştan sona anlatır: bir eklentinin ne olduğu, bir eklentinin kendini ana bilgisayara nasıl tanıttığı, dışa aktarımlarının ve yetenek beyanlarının nasıl yazılacağı, ana bilgisayarın uyguladığı çalışma zamanı sınırları ve ana bilgisayar işlevleri, bir eklentiyi kataloğa taşıyan Plugin varlığı, bir Recipe’in ya da FeatureRecipe’in bir eklentiye nasıl başvurduğu ve bir eklentiyi diskteki bir .wasm dosyasından bir derlemenin kullandığı, doğrulanmış ve özet değeriyle sabitlenmiş bir yapıta götüren yayımla→çek→derle yaşam döngüsü.
Eşlik eden plugin-contract.md sayfası soketleri belgeler: eklentilerin bağlandığı işlem hattı noktalarını ve her soketin aldığı ve ürettiği girdi/çıktı biçimlerini. Bu kılavuz ise eklentiyi belgeler: varlığı, yetenek yüzeyini ve yaşam döngüsünü. Eklentinizin hangi soketi hedeflediğini öğrenmek için sözleşme sayfasını, onu nasıl yazıp yayımlayacağınızı öğrenmek için bu sayfayı okuyun.
Görevin tamamı için bir başvuru yerine uygulamalı bir yol arıyorsanız, bir sağlayıcı yazmak küçük bir sağlayıcı konuğunu baştan sona oluşturur: tanımlayıcı, derleme, varlık, bağlama ve çıktısını okuyabileceğiniz bir işleme; buna ilk taslağın genellikle karşılaştığı ret ve bu retin nasıl okunacağı da dahildir.
1. Wasm plugin nedir
Wasm plugin, derleyiciyi belirlenmiş bir soket noktasında genişleten bir WebAssembly modülüdür. Go ana ikili dosyası buluta özgü veya altyapıya özgü hiçbir mantık içermez; alana özgü tüm zekâ — şablon işleme, biçim dönüştürme, ilke değerlendirme, lint denetimi — plugin’lerin içinde yer alır. Ana bilgisayar (host) işlem hattını yönetir ve her soketin yükünü ABI sınırının ötesine konuğa (guest) iletir; konuk alan işini yapar ve o soketin sonuç biçimini döndürür. Her soketin yükü ve sonucu kanonik CBOR olarak taşınır; iki istisna vardır: bir CLI plugin’i argüman vektörünü JSON metni olarak alır ve bir çıkış kodu ile akış olarak gönderdiği metinle yanıt verir; describe öz raporu ise JSON metnidir. Plugin sözleşmesinin her soketle ilgili bölümü o soketin kodlamasını belirtir ve konuk bu kodlamayı, kitinin yük türünün zaten sağladığı giriş noktaları aracılığıyla okuyup yazar; böylece hiçbir konuk baytları elle ayrıştırmaz.
Bir plugin, derleme zamanı saflığını koruyan bir güvenlik duvarının arkasında çalışır. Ana bilgisayar modülü, yetenekleri reddeden bir yapılandırma altında gömülü bir Wasm çalışma zamanı üzerinden yükler ve yürütür: ağ soketi yok, dosya sistemi yok, ortam yok, stdio atılır ve gözlemlenebilir duvar saati derlemeden bağımsız sabit bir ana dondurulmuştur. Konuğun denediği her G/Ç çağrısı çağrı sınırında başarısız olur; dolayısıyla bir plugin çalışma zamanı durumuna erişemez. Plugin’leri bu güvenlik duvarını göz önünde bulundurarak yazın: bir plugin kendisine verilen yükü dönüştürür ve ana bilgisayarın olduğu gibi tükettiği bir sonuç döndürür; determinizm sizin sorumluluğunuzdadır — özdeş girdi özdeş çıktı baytları üretmelidir. Uzak içerik için onaylanmış tek kanal, ana bilgisayarın aracılık ettiği harici girdi getirme işlemidir (Bölüm 4); bu işlem konuğa canlı ağ erişimi vermek yerine baytları özete sabitlenmiş bir disiplin altında sunar.
Bir plugin’in hedefleyebileceği soketler — aralarında topoloji oluşturmadaki mutasyon geçidi, statik analizdeki doğrulama geçidi, FeatureRecipe işlem hattı, bant dışı linter ve provider işleme soketi bulunur — ve her soketin girdi/çıktı biçimleri plugin-contract.md sayfasında belgelenmiştir. Bir plugin’in hangi sokete hizmet ettiği, metadata.pluginType alanında bildirdiği tek değerdir; bu alanın kabul ettiği değerlerin tamamı entities/plugin.md §“metadata.pluginType” başvuru girdisinde yer alır. Bu kılavuzdaki örnekler provider (IR düğümlerini provider’a özgü yapıtlara dönüştürür), linter (yazılmış içeriği inceler ve tanılamalar üretir) ve pipeline-step (bir FeatureRecipe’in ya da bir Recipe’in pipeline: alanında, işlenmiş belge kümesine yama uygulayan bir adım) değerlerini kullanır.
Konuğu, ana bilgisayara karşı üç dilli plugin geliştirme kiti (PDK) — Go, Rust veya TypeScript — aracılığıyla yazarsınız. PDK, alttaki Wasm araç zincirini, her soketin taşıdığı girdi ve çıktı biçimleri için Aggrega türlü oluşturucularla sarar.
2. describe() öz raporu
Her plugin, plugin’in öz raporunu döndüren bir describe() işlevini dışa aktarır: uyguladığı soket türü veya türleri, hedeflediği ABI sürümü, öne sürdüğü yetenekler (soket türüne göre okunur; yani bir provider veya bir pipeline adımı için yetenek adları, bir ayrıştırıcı veya bir içe aktarıcı için önekli kaynak biçimleri), içe aktardığı host işlevleri ve sunduğu her giriş noktasının dışa aktarım başına yeteneği. describe(), plugin’in ne olduğuna ve ne yaptığına dair kendi beyanıdır.
Öz rapor, güven modelinin dayanak noktasıdır. Plugin’i kataloğa taşıyan Plugin varlığı (Bölüm 5) aynı olguları yazılmış beyanlar olarak yeniden ifade eder ve host, varlığın beyanlarını plugin’in describe() çıktısıyla iki anda çapraz denetler: yayımlama sırasında, herhangi bir bayt kayıt defterine ulaşmadan önce ve yükleme sırasında, plugin çalışmadan önce. Bir uyuşmazlık, açıkça bildirilerek işlemi durdurur. Varlık, insanların okuyabildiği ve katalogda görünen yüzeydir; describe() ise host’un varlığı karşısında doğruladığı esas kayıttır. İkisini birbiriyle uyumlu olacak şekilde yazın; çapraz denetim tam da ikisinin birbirinden saptığı durumu yakalamak için vardır. Denetim, varlığın neyi beyan ettiğine bakar, neyi dışarıda bıraktığına değil: ikili dosyanın bildirdiğinden daha azını beyan eden bir varlık — örneğin bir dışa aktarım ekleyen bir yeniden derlemeden geride kalmış bir varlık — artık ikili dosyanın yaptığı her şeyi tanımlamasa da yine yüklenir.
3. Dışa aktarımları ve yetenek beyanlarını yazma
Bir plugin bir veya daha fazla dışa aktarım sunar: host’un yönlendirdiği adlandırılmış giriş noktaları (örneğin render_node, lint_naming, step). Her dışa aktarım bir yetenek bloğu taşır: yazarın o dışa aktarımın ne yaptığına dair beyanı. Bir dışa aktarımın yeteneği dört alandan oluşur:
name— dışa aktarımın ABI adı, yani host’un yönlendirdiği ad. Zorunludur.operates— dışa aktarımın gerçekleştirdiği pipeline işlemi:patch(render edilmiş mevcut bir belgeyi değiştirir) veyaemit(yeni bir belge ekler). Bu, beyan edilmiş bir yetenek iddiasıdır. Host bunu yayımlama ve yükleme sırasında plugin’indescribe()öz raporuyla karşılaştırır; bu nedenle entity’de yazılan beyan ile plugin’in kendi açıklaması uyuşmalıdır. Bu, dışa aktarım hakkında doğrulanan bir beyandır, bir yönlendirme anahtarı değildir: render sırasında bir adımın gerçekte yaptığı işlem bu alandan seçilmez, guest’in döndürdüğü sonuçla taşınır. Alan yoksa hiçbir işlem beyanı taşınmaz.scope— dışa aktarımın üzerinde çalıştığı belge kökü:own(düğümün kendi render edilmiş belgeleri) veyahost(bileşen kapsamlı bir FeatureRecipe’in bağlı olduğu bileşenin belgeleri). Bir pipeline adımının plugin’i çalışmadan önce host, adımın beyan edilen dışa aktarım kapsamını okur ve o kapsamın belgelerini render eden provider’ın plugin’inspec.pipelineStep.capabilitiesalanında (Bölüm 5) yer almasını zorunlu kılar:ownkapsamlı bir dışa aktarım, düğümün kendi belgelerini render eden provider’a;hostkapsamlı bir dışa aktarım ise host bileşenin provider’ına göre denetlenir; boş bir kapsam bu denetim için varsayılan olarakownkabul edilir. Bu, adımdan önce çalışan provider uyumluluğu kapısıdır; bir guest işleminin gerçekte dokunduğu belge bu beyan edilen alandan seçilmez, guest’in döndürdüğü sonuçta işlem başına adlandırılır. Alan yoksa varsayılanown’dur.selector— dışa aktarımın neye etki ettiğine dair serbest biçimli, insanların okuyabileceği bir açıklama (örneğinworkloads carrying a pod template). Katalog okurları veaggrega inspectyüzeyi için belgelemedir; derleyici bunu yorumlamaz.
Dışa aktarımları okunmasını istediğiniz sırayla yazın; girdiler entity’de ve inspect çıktısında yazarın sırasını korur. Yazılmış hiçbir dışa aktarımı olmayan bir plugin, hiçbir dışa aktarım yüzeyi beyan etmez; bu, soketi dışa aktarım başına bir yetenek beyanı gerektirmeyen bir plugin için geçerlidir.
4. Çalışma zamanı sınırları ve host fonksiyonları
Bir plugin varlığı, host’un plugin’i nasıl yükleyip çalıştıracağını kısıtlayan isteğe bağlı bir runtime bloğu taşıyabilir.
Bellek ve zaman sınırları. maxMemoryPages, plugin’in doğrusal belleğini Wasm sayfası cinsinden sınırlar (sayfa başına 64 KiB); timeoutMs, plugin’in kendi kodunun tek bir çağrı sırasında ne kadar süre çalışabileceğini milisaniye cinsinden sınırlar. Plugin’in çağırdığı host fonksiyonlarının içinde geçen süre bu sınıra sayılmaz. Linux’ta ölçü, guest’i çalıştıran iş parçacığının işlemci süresidir; dolayısıyla meşgul bir makinede guest’in bir işlemci beklerken geçirdiği süre de sayılmaz; diğer sistemlerde ise geçen gerçek süredir. Yeni yüklenmiş bir plugin’e yapılan ilk çağrı, o çağrının içinde çalışan guest dil çalışma zamanının tek seferlik başlatılmasını da sayar. Her iki sınır da varsayılanlı isteğe bağlıdır: sıfır ya da belirtilmemiş olması platformun varsayılan sınırını uygular. Varlık hiçbir sınır bildirmediğinde yükleyici her plugin’i platform varsayılanıyla sınırlar; böylece bir yükleme hiçbir zaman sınırsız, bir çağrı da hiçbir zaman iptal edilemez olmaz. Bir bağlantı gerçekten varsayılanın izin verdiğinden fazla bellek ya da süre gerektirdiğinde sınırı varlık üzerinde yükseltin.
Host fonksiyonları. hostFunctions, plugin’in içe aktardığı host fonksiyonu adlarını kaydeder. Bu makine tarafından türetilen bir alandır; bunu yazmayın. aggrega plugin sync, host fonksiyonlarını doğrudan .wasm import bölümünden okur ve alanı sizin için varlık dosyasına kaydeder; yayımlama ise bunları ikili dosyadan yeniden türetir ve kaydı farklı olan bir varlığı reddeder; böylece bir plugin, ikili dosyasının gerçekten içe aktardığı host fonksiyonlarını tam olarak alır ve bunlar özenle seçilmiş bir izin listesine göre doğrulanır (izin listesi dışındaki bir import açıkça reddedilir). Kayıt, yayımlanan ikili dosyanın bir anlık görüntüsüdür; içerik adresli plugin: referansının yayımlanan baytların bir anlık görüntüsü olmasıyla aynı şekilde: yayımlama anındaki ikili dosyayı yansıtır ve plugin çekildiğinde yeniden türetilip doğrulanır. Yayımlamadan önce yerel bir .wasm dosyasının içe aktardığı host fonksiyonlarını, yani aggrega plugin sync komutunun kaydettiği değeri görmek için aggrega inspect --plugin <file.wasm> komutunu çalıştırın.
Seçilmiş host yüzeyi. Host fonksiyonlarından üçü genel amaçlıdır: aggrega_log (host’un log hedefinde tek bir log satırı olarak yayılan bir düzey ve bir ileti), aggrega_emit_warning (bir kod, bir ileti ve bir yol; host’un çağrıdan sonra gösterdiği yapılandırılmış bir uyarı olarak biriktirilir) ve aggrega_fetch_external_input (aşağıdaki sabitleme disiplini altında girdinin baytlarıyla yanıtlanan bir URL). PDK üçünü de her dilde sarmalar — Go: aggrega.Log, aggrega.EmitWarning, aggrega.FetchExternalInput; Rust: log, emit_warning, fetch_external_input; TypeScript: log, emitWarning, fetchExternalInput — böylece bir guest ham ABI yerine tipli bir fonksiyon çağırır. Kaynak ve ayrıştırma geri çağrıları (edinilmiş bir kaynağın dilimlerini okuyan ya da host aracılığıyla ayrıştırılmış bir ağaç elde eden guest için) ve her geri çağrının yuvalarının taşıdığı kodlama plugin-contract.md içinde listelenmiştir.
Yerel kaynak içeriği host üzerinden gelir, asla dosya sisteminden gelmez. Bir provider render plugin’i kaynağını asla diskten okumaz; bir dosya sistemi çağrısı çağrı sınırında başarısız olur. Host, render yükü içinde guest’e bir kaynak listesi verir — her girdinin kaynak köküne göreli yolu ve bir dizin olup olmadığı, sıralı biçimde, dosya içeriği olmadan — ve guest buna kendi yerleşim mantığını uygular, ardından seçtiği dosyaları tam olarak kaynak geri çağrıları aracılığıyla geri okur; bu geri çağrılar host’un kaynak kökü altında okuduğu baytları döndürür. Yuva başına yük biçimleri ve geri çağrılar plugin-contract.md içinde belgelenmiştir.
Uzak içerik harici girdi getirme yoluyla gelir. Uzak içeriğe (bir chart arşivi, uzak bir şema belgesi) ihtiyaç duyan bir plugin, PDK’nın getirme sarmalayıcısını çağırır. Kablo üzerinde guest, URL’yi aggrega_fetch_external_input fonksiyonuna UTF-8 metin olarak geçirir ve kanonik CBOR biçiminde tek bir yanıt alır; bu yanıt ya getirilen baytları ham olarak ya da makinece eşleştirilebilir kodunun yanında bir hata iletisini taşır; sarmalayıcı yanıtı bayt-ya-da-hata biçimine çözer. Baytlar, geçerli UTF-8 olmayan bir yük dahil, tam getirildiği gibi gelir ve sıfır uzunluklu bir yük hata yerine boş bayt olarak döner. Host, URL’yi harici girdi sabitleme disiplini altında sunar:
- Release’in kilit dosyasında zaten sabitlenmiş bir URL, yerel içerik adresli depodan sunulur ve her okumada kayıtlı özetine göre doğrulanır. Depoda eksik bir blob, kayıtlı özete göre ağdan yeniden doldurulur; özeti doğrulanmış bir yeniden doldurma çıktıyı değiştiremez.
- Sabitlenmemiş bir URL, URL’yi ve çözümü belirten bir hatayla reddedilir. Bir derleme, kilit dosyasının kaydettiği kapanışı render eder; dolayısıyla hiçbir derleme sabitlenmemiş bir referansı getirmez ve bunu yaptıran bir ayar da yoktur.
- Sabitleme, Release’in bağımlılıkları çözümlendiğinde gerçekleşir:
aggrega pull, render’ının hangi harici girdileri istediğini bulmak için Release’i render eder, her birini getirir ve bağımlılık sabitlemelerinin yanında kilit dosyasına kaydeder. Böylece bir plugin yazarının döngüsü şudur: bir kez çözümleyin, ardından istediğiniz sıklıkta çevrimdışı derleyin.
İzin verilen şemalar https, yalnızca loopback host’larına yönelik http ve (manifest özetiyle sabitlenen) oci şemalarıdır. Kilit dosyası her sabitlenmiş girdiyi (URL’sini, sha256 özetini, boyutunu ve onu gerektiren plugin’leri) kaydeder; böylece yeniden derleme aynı baytları yerel depodan sunar: yeniden üretilebilir ve sabitlendikten sonra çevrimdışı.
Go PDK ile:
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)}Neler başarısız olur ve neden.
- Bir dosya sistemi ya da ağ çağrısı çağrı sınırında başarısız olur: guest’in önceden açılmış dizini ve soketi yoktur. Bu, bir dosyayı okumaya çalışan bir kütüphane bağımlılığı dahil her kod yolu için geçerlidir; bunun yerine kaynağı kaynak geri çağrıları aracılığıyla okuyun.
wasi_snapshot_preview1,extism:host/envveextism:host/userdışındaki bir modül altındaki import, yükleme sırasında modülü ve import’u belirten bir tanılamayla başarısız olur. İzin verilen bir modül içindeki tek tek WASI fonksiyon adları asla sansürlenmez; statik olarak bağlanmış bir dil çalışma zamanının kullanılmayan dosya sistemi ve soket import’ları sorun değildir, çünkü bir import’u adlandırmak hiçbir yetki vermez.- Kilit dosyasının sabitlemediği bir URL’nin getirilmesi, URL’yi belirten bir hatayla başarısız olur; çözüm, Release’in render’ının tükettiği her harici girdiyi sabitleyen
aggrega pull --release <release>komutunu çalıştırmak ve ardından derlemektir.
Giden ağ erişimi için bir host izin listesi alanı yoktur. Bir plugin derleme zamanında asla ağa ulaşmaz (bu, ahead-of-time sınırıdır); dolayısıyla yazılacak böyle bir alan yoktur. Uzak içerik, asla ortam ağ erişimiyle değil, yukarıdaki host aracılı, özetle sabitlenmiş harici girdi kanalıyla gelir.
Yapılandırma. configKV, çalışma zamanının başlangıçta plugin’e verdiği dizeden dizeye bir eşlemdir. Girdiler yazar sırasını korur; böylece yayılan kayıt çalıştırmalar arasında bayt düzeyinde aynıdır. Belirtilmemesi, çalışma zamanının varsayılan boş yapılandırmasını geçerli bırakır.
5. Plugin varlığı
Bir plugin kataloğa bir Plugin varlığı olarak girer; bu varlık, plugin’in yazım ve meta veri yüzeyidir. Varlık, plugin’in ne olduğunu bildirir ve .wasm yapıtını işaret eder; derleyici plugin’in davranışını yorumlamaz ve sabitlenmiş başvuruyu yönlendirir, baytları ise Wasm çalışma zamanı yürütür.
apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: aws-secrets-manager version: 1.2.0 pluginType: pipeline-stepspec: 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 credentialAlanlar:
- Bilinçli olarak yapıt konumu alanı yoktur. Varlık
.wasmdosyasına bir işaretçi taşımaz ve şema da böyle bir alan kabul etmez. Bir plugin’in yapıt konumu, kimliğinden türetilir:plugin/<pluginType>/<name>depo yolunu oluşturanmetadata.pluginType/metadata.namekoordinatı ile çalışma alanının yapılandırıldığı kayıt defteri. Bu nedenle yazılacak bir konum da, yanlış yazılabilecek bir konum da yoktur. Çözümlenen içerik özeti her Release için o Release’in kilit dosyasına kaydedilir ve derleme, getirilen baytları buna karşı doğrular: kimlik varlıkta, doğrulanmış baytlar kilit dosyasında. metadata.version: varlığın yayımladığı sürüm; bu, konuğundescribe()içinde bildirdiği kendi derleme kökeni sürümüne eşit olmalıdır. Plugin yazarı.wasmdosyasını derleme zamanında sürümler: derleme sürümü konuğa damgalar ve sürümü bir sürüm etiketinden alan bir derleme, sürüm numarasını yalnızca o etiketin işaret ettiği commit’e damgalar. Varlığınmetadata.versionalanı da aynı sürümü adlandırır. Yayımlama kapısı ikisini çapraz denetler ve bir uyuşmazlıkta durur; böylece varlık her zaman sunduğu ikili dosyanın tam sürümünü adlandırır.aggrega plugin gen-catalog --plugin(aşağıda), konuğun bildirdiği sürümü ürettiği varlığa kopyalar; konuk etiketli commit’ten derlendiyse bu, sürüm numarasıdır. Zorunludur.metadata.pluginType: bu plugin’in uyguladığı soket türü;provider,linter,pipeline-step,governance,cli,parserveimporterarasından seçilir. Bir plugin tam olarak birini uygular. Adresleme bloğundanameveversionyanında yer alır ve türetilen koordinatın<pluginType>kesimini sağlar. Zorunludur.spec.abiVersion: plugin’in hedeflediği ana bilgisayar/konuk ABI sürümü. Kabul edilen değerv1beta1’dir; gelecekteki bir ABI revizyonu kabul edilen yeni bir değer ekler. Zorunludur.- Soket türünüze ait,
capabilitiestaşıyan blok: bir plugin, sunduklarınımetadata.pluginTypealanına ait blokta bildirir ve bir girdinin ne anlama geldiğini belirleyen bu bloktur.spec.provider.capabilities, bir sağlayıcının sunduğu yetenekleri adlandırır (helmveyacomposegibi yetenek adları).spec.pipelineStep.capabilities, adımınızın işlenmiş çıktısıyla uyumlu olduğu sağlayıcıları adlandırır.spec.parser.capabilities, bir ayrıştırıcının okuduğu kaynak biçimlerini adlandırır; her biriparse:<format>olarak yazılır.spec.importer.capabilities, bir içe aktarıcının varlık taslakları çıkardığı yabancı biçimleri adlandırır; her biriimport:<format>olarak yazılır. Go ile yazılmış bir içe aktarıcı, biçimine bağlı olmayan her şeyi (puanlama, başvurma ya da taslak çıkarma kararı, taslaklar ve bunların işlenmesi ve ayarları) Go kitinin içe aktarıcı paketinden,github.com/aggrega-ai/aggrega-pdk/go/pkg/importerpaketinden alabilir. Birlinter,governanceveyacliplugin’i hiçbir yetenek sunmaz ve dört bloktan hiçbirini taşımaz. Girdiler yazarın sırasını korur ve her liste açık, sınanmış bir iddiadır: plugin’i gerçekten hangi hedeflere karşı derleyip sınadıysanız onları bildirin, çünkü bir tüketici tam olarak listelenenlere göre çözümleme yapar. Bir ardışık düzen adımı için bu iddia işleme sırasında uygulanır: bir adım bir kapsama dokunduğunda, o kapsamın belgelerini işleyen sağlayıcı plugin’inizin iddia ettikleri arasında değilse derleme durur. Bu nedenle boş bir liste hiçbir sağlayıcıyla eşleşmez ve adımı hiçbir yerde kabul ettirmez. spec.signature: plugin’in ekli imzasına isteğe bağlı, betimleyici bir işaretçi (Bölüm 8). 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 ettirmez. Uygulayıcı denetim, çekme sırasında uygulanan kayıt defteri başına güven ilkesidir.spec.runtime: Bölüm 4’teki isteğe bağlı yürütme kısıtlamaları bloğu. YazarmaxMemoryPages,timeoutMsveconfigKValanlarını yazar;hostFunctionsmakine tarafından türetilir ve yazılmaz,aggrega plugin synctarafından kaydedilir ve yayımlama tarafından doğrulanır.spec.exports: Bölüm 3’teki dışa aktarım başına yetenek iddiaları (name,operates,scope,selector).
Varlığı .wasm dosyanızdan üretmek. Varlığın makineye ait kısımlarını elle yazmanız gerekmez. aggrega plugin gen-catalog --plugin <file.wasm>, konuğun describe() öz raporunu okur ve bundan, sizin sağladığınız küçük bir yazılmış katmanla (kimlik, çalışma zamanı sınırları ve varsa sağlayıcı bloğu) birlikte yayımlamaya hazır bir Plugin varlığı üretir. Üreteç, doğruluk kaynağı ikili dosya olan alanları (dışa aktarım iddiaları, yetenek sözleşmesi, komut yansısı ve ana bilgisayar işlevi kaydı) damgalar ve metadata.version alanını konuğun describe() derleme kökeni sürümünden kopyalar; katman ise yalnızca ikili dosyanın bildirmediklerini sağlar. Üçüncü taraf bir plugin yazarı için desteklenen yol budur: .wasm dosyanızı derleyip sürümleyin, ardından makineye ait alanların ikili dosyayla uyum içinde kalması için varlığı yeniden üretin. Sürüm, baytlarla ilgili bir olguyu değil bir sürümü adlandıran tek kopyalanmış alandır; bu nedenle üretimi, sürüm etiketinin işaret ettiği commit’in bir derlemesinden yapın ya da bir geliştirme derlemesinden başlıyorsanız, varlığı taşıyan commit’i etiketlemeden önce üretilen varlıkta metadata.version alanını sürüme ayarlayın. Derleme kökeni sürümü taşımayan bir konuktan sürümlü bir varlık üretilemez; önce konuğu derleme zamanında sürümleyin.
Varlığının yanındaki .wasm. Bir eklenti yazarken, bir derlemenin getireceği hiçbir şey henüz yayımlanmamıştır; bu yüzden bir derleme, eklentinin .wasm dosyasını bir katalog dizininde Plugin varlığının yanından, varlığın eklenti türünden ve adından türetilen bir adla okur: pipeline-step/patch için bu ad pipeline-step--patch.wasm olur. Küçük harfler, rakamlar ve kısa çizgilerin çoğu bu ada oldukları gibi yazılır; diğer her karakter kaçışlı bir biçimde yazılır, birkaç konumdaki kısa çizgi de öyle — bu yüzden önemli olduğu yerde, eksik bir .wasm için verilen ret, A plugin’s .wasm is not on this machine (bir eklentinin dosyası bu makinede değil), adı tam olarak verir. aggrega lint <plugin.yaml>, ikili dosya eklentiyi kendisi taşımadığı sürece .wasm dosyasını aynı yerden okur — kendisine verilen varlık dosyasının yanından, o dosya hangi dizinde bulunuyorsa oradan — ve .wasm dosyasının bildirdiği ama varlığın dışarıda bıraktığı her dışa aktarım, yetenek veya sözleşme için bir bildirim yazdırır. Orada hiçbir .wasm yoksa lint, o raporu atladığını söyler, aradığı dosyayı ve dizini belirtir ve sonucu değişmez.
Alan alan başvuru için ../entities/plugin.md varlık sayfasına bakın.
6. Bir eklentiye başvurma
Bir pipeline adımı veya bir eklenti soketi, bir eklentiye doğrudan .wasm yapıtıyla değil, Plugin varlık URI’si ile, yani varlığın kimliğiyle başvurur. Varlık; özet sabitlemesini, yetenek beyanlarını, çalışma zamanı sınırlarını ve imzayı taşıyan katmandır; bir tüketici bunların tümünü varlığa başvurarak edinir.
Bir plugin alanında bırakılan yalın bir .wasm yolu veya ham bir yapıt başvurusu yükleme sırasında reddedilir: hiçbir Plugin varlığı onunla eşleşmez, bu nedenle eklenti çözümlemesi açıkça başarısız olur. Varlık URI’si zorunludur; varlık üzerinden dolaylı başvuru isteğe bağlı bir kolaylık değil, sözleşmenin kendisidir. Bir FeatureRecipe pipeline adımı varlığı pipeline[].plugin içinde adlandırır; pipeline yazım yüzeyi için ../entities/featurerecipe.md sayfasına bakın.
İki veya daha fazla plugin birbirine bağlı olduğunda — yani bir plugin’in çıktısının diğerinin girdisi olduğu bir Fetcher ve Injector çiftinde olduğu gibi, ortak bir devir sözleşmesinde uzlaşmaları gerektiğinde (plugin-contract.md içinde açıklanan Two-Part Plugin Principle) — bu sözleşmeyi bir kez yazın ve JSON devir yapısını her plugin’de ayrı ayrı yeniden tanımlamak yerine her plugin’in bu tek tanıma bağlı olmasını sağlayın. Ortak yapı, plugin’lerin birbirine aktardığı JSON yapısıdır ve her iki plugin’in de başvurduğu tek bir SchemaLibrary girdisinde bulunabilir. Sözleşme için tek bir kaynak, sözleşme geliştikçe birbirine bağlı plugin’leri eşgüdümlü tutar; bağımsız yeniden tanımlar zamanla birbirinden ayrılır ve bu ayrılık ancak ikisi çalışma zamanında artık uyuşmadığında ortaya çıkar. Önerilen, Wasm kodunu değil sözleşmeyi paylaşmaktır — her plugin kendi artifact’i olarak kalır.
7. Yayımlama → çekme → derleme yaşam döngüsü
Bir plugin, diskteki bir .wasm dosyasından derlemenin tüketebileceği, doğrulanmış bir yapıta üç aşamada ulaşır.
Yayımlama. aggrega push, bir Plugin entity’sini ve onun .wasm dosyasını, metadata.version ile etiketlenmiş tek bir OCI manifest’i olarak birlikte yayımlar: entity YAML’ı manifest’in config blob’udur ve .wasm aynı manifest’in bir katmanı olarak taşınır. Çiftin tek bir etiketli manifest olarak yayımlanması, push işlemini atomik kılan şeydir — bir yarının yayımlanıp diğerinin yayımlanmadığı bir zaman aralığı yoktur — ve bu manifest üzerindeki tek bir imzanın her iki yarıyı da kapsamasının nedeni de budur. Her iki yarı da manifest üzerinde adlandırılmıştır; bu nedenle sürüm etiketini çeken genel bir OCI istemcisi entity’yi entity.yaml dosyasına, çalıştırılabilir dosyayı ise entity.wasm dosyasına yazar.
Herhangi bir bayt yerine ulaşmadan önce yayımlama denetimlerini çalıştırır. Entity önce, bir katalog yüklemesinin okuduğu biçimde Plugin şemasına göre okunur; böylece anlamsal sürüm olmayan bir metadata.version — ya da şemadan herhangi bir başka sapma — .wasm okunmadan önce reddedilir. Ardından .wasm yüklenir ve describe() öz raporu, entity’de yazılmış yetenek beyanlarıyla çapraz denetlenir — bir uyuşmazlık yüksek sesle durdurur; böylece yayımlanmış bir entity, birlikte gönderdiği plugin’in bildirmediği bir şeyi hiçbir zaman beyan etmez. describe() derleme kaynağı sürümü, commit edilmemiş değişiklikler içeren bir çalışma ağacından yapılan derlemeye damgalanan -dirty işaretini taşıyan bir konuk reddedilir: bu sürüm, derlenen şeyi içermeyen bir commit’i adlandırır. Bir commit’ten derlenmiş geliştirme sürümü (1.0.0-3-g1a2b3c4) ve bir ön sürüm (1.0.0-rc.1) yayımlanır. Kaydedilen metadata.version, konuğun describe() derleme kaynağı sürümüyle çapraz denetlenir ve bir sapma yayımlamayı durdurur; dolayısıyla ikisinin uyuşması gerekir. Her iki ret de aynı biçimde giderilir: plugin’i, sürümün etiketinin adlandırdığı commit’in temiz bir checkout’undan derleyin; böylece doğrudan sürüm numarasının kendisini raporlar — yeni bir sürüm için entity’yi yayımladığı kaynakla birlikte commit edin ve önce o commit’i etiketleyin. Bir geliştirme derlemesinin raporladığı sürümü entity’ye kopyalamak bir onarım değildir: bu, o derlemeyi hiçbir sürüm etiketinin adlandırmadığı bir sürüm altında yayımlar. .wasm dosyasının içe aktardığı host fonksiyonları ikili dosyadan türetilir ve spec.runtime.hostFunctions içinde commit edilmiş kayıtla karşılaştırılır; bir sapma yayımlamayı durdurur ve alanı yeniden kaydeden aggrega plugin sync komutunu belirtir, çünkü alan makineye aittir ve bir yayımlama commit edilmiş entity dosyasını hiçbir zaman yeniden yazmaz. Yayımlanan entity, damgalanmış host fonksiyonu kaydını taşır; .wasm içerik özeti, çiftin yayımlandığı manifest’in bir özelliğidir ve entity’ye yazılmak yerine bir tüketici için Release kilit dosyasına kaydedilir.
Çekme. aggrega pull, bir Release’in tüm bağımlılıklarını çözümler ve her katalog entity’sini ve uzak yapıtı bir sürüme ve içerik özetine sabitleyen, Release başına bir kilit dosyası yazar. Yayımlanmış bir Plugin bu bağımlılık çözümlemesi aracılığıyla çözümlenir; .wasm dosyası onu taşıyan manifest ile birlikte getirilir ve baytlar kilit dosyasının kaydettiği içerik özetine göre doğrulanır. Çekme ayrıca host fonksiyonlarını doğrulanmış .wasm dosyasından yeniden türetir ve bunları damgalanmış hostFunctions kaydıyla karşılaştırır; ikisi uyuşmazsa durur — bu, özet sabitlemesinin üzerinde, damgası kendi içe aktarımlarından üretilmemiş bir ikili dosyayı yakalayan derinlemesine savunma denetimidir. Kayıt defterinin güven ilkesi imza gerektiriyorsa, entity’nin imzası bu aşamada getirilir, doğrulanır ve kilit dosyasına doğrulanmış bir olgu olarak kaydedilir (Bölüm 8). Doğrulama derlemede değil, her zaman çekmede gerçekleşir — derleme önceden derleme (ahead-of-time) açısından saf kalır.
Derleme. aggrega build, sabitlenmiş ve doğrulanmış plugin’i çözümlenmiş bağımlılıklardan tüketir. Derleyici özetle sabitlenmiş başvuruyu yönlendirir ve Wasm çalışma zamanı baytları yürütür; yükleme kapısı, plugin çalışmadan önce describe() çapraz denetimini ve host fonksiyonu ile çalışma zamanı sınırı denetimlerini yeniden çalıştırır.
8. İmzalama ve güven
Bir Plugin varlığı, diğer tüm katalog varlıklarıyla tamamen aynı şekilde imzalanır: manifest’in özeti imzalanır ve bir OCI referrer olarak eklenir. .wasm yapıtı ayrıca imzalanmaz ve ayrı bir imzaya ihtiyaç duymaz; özeti imzalanan manifest’in ta kendisinin bir katmanıdır, dolayısıyla imza onu doğrudan kapsar: .wasm üzerinde yapılan bir oynama manifest özetini değiştirir ve imzayı bozar.
İmzalama, yayımlama sırasında isteğe bağlıdır; doğrulama ise çekme sırasında kayıt defteri başına güven politikası tarafından zorunlu kılınır. İmza gerektirecek şekilde yapılandırılmış bir kayıt defteri, gerekli bir imza eksik, güvenilmeyen veya geçersiz olduğunda çekme işlemini durdurur. Varlıktaki spec.signature bloğu, imzanın nerede bulunduğunu ve nasıl üretildiğini gösteren bir belgeleme işaretçisidir; katalog okuyucuları için olguları kaydeder ve kabulü kendisi denetlemez. Denetimi yapan, çekme anındaki politikadır.
Komutlar ve bayrakları, yayımlama ve tüketme yüzeyleriyle birlikte belgelenmiştir; bkz. ../cli/aggrega-sign.md, ../cli/aggrega-push.md ve ../cli/aggrega-pull.md. Bu kılavuz bayrak tablolarını yinelemez; komut yüzeyinin tek yeri o sayfalardır.
9. Varlığın sürümlenmesi
Bir Plugin varlığı, metadata.version içinde katı bir Semantic Version taşır. Yayımlanmış bir sürüm değiştirilemez: kayıt defterinde zaten var olan bir sürümü farklı içerikle yeniden yayımlama girişimi yayımlama kapısında reddedilir.
Bir plugin varlığını değiştirip yeniden yayımladığınızda, yayımlama disiplini değişikliği daha önce yayımlanmış sürüme göre sınıflandırır ve sürüm artışının buna uymasını gerektirir. Sınıflandırma, sürüm artışı ölçütüdür: yalnızca belgelendirmeyi veya yorumları etkileyen bir değişiklik PATCH; katı biçimde eklemeli bir değişiklik (yeni bir isteğe bağlı alan, yeni bir girdi) MINOR; bir kaldırma, bir tür daraltma veya daha önce isteğe bağlı olan bir alanın zorunlu hâle gelmesi MAJOR olarak sınıflandırılır. Gerekenden fazla artışa her zaman izin verilir; gerekenden az artış, gereken artışı belirten bir tanılamayla durur. Bir varlığın ilk yayımı artış denetimini atlar ve hiçbir doğrulama yapılmadığını belirten bir uyarı gösterir. Denetimi yayımlamadan önce aggrega lint --pre-publish ile çalıştırın; ölçütün tamamı ve kural başına ayarlar için ../cli/aggrega-lint.md sayfasına bakın.
Bir Plugin’in extends yüzeyi yoktur; bu nedenle kataloğun Components ve Features öğelerini yöneten kalıtım kuralları ona ulaşmaz. Bir plugin varlığını yöneten sürümleme disiplini, sürüm artışı ölçütü ve değiştirilemezliktir.
10. Çapraz başvurular
authoring-a-provider-walkthrough.md— boş bir dizinden işlenmiş çıktıya kadar uçtan uca oluşturulan bir provider konuğu.plugin-contract.md— bir plugin’in hedeflediği soket noktaları ve sokete özgü girdi/çıktı biçimleri.policy-socket.md— yönetişim soketinin ayrıntılı anlatımı: dört rolü, karar önem düzeyleri, operatör girdi kanalı, derleyiciyle birlikte gelen iki motordan herhangi biri için politika yazma ve başvuru politika konukları.core-importers.md— derleyicinin okuduğu her biçim için bir tane olmak üzere, Go kitinin içe aktarıcı paketi üzerine kurulu kendi içe aktarıcıları: her birinin neyi okuduğu, ayarları ve her derleyici sürümüyle yayımlanmaları.../compatibility.md— plugin kitlerinin nasıl sürümlendiği ve bir sürüme göre derlenen bir plugin’in bir sonraki sürümde de yüklenmeye devam etmesini neyin sağladığı.../entities/plugin.md—Pluginvarlığının alan alan başvuru belgesi.../entities/featurerecipe.md— bir plugin’e varlık URI’si ile başvuran FeatureRecipepipeline:yazım yüzeyi.../cli/aggrega-lint.md— yayımlama denetleyicisi, sürüm artırma ölçütleri ve değişmezliğin uygulanması.../cli/aggrega-inspect.md— birPluginvarlığının yeteneklerini, çalışma zamanı sınırlarını ve imzasını inceleme.../cli/aggrega-push.md,../cli/aggrega-pull.md,../cli/aggrega-sign.md— yayımlama, tüketme ve imzalama komut yüzeyleri.