Derleme işlem hattı (üst düzey)
Bu bölüm Go derleyicisinin iç fiziğini ayrıntılandırır; soyut YAML’ın derleme işlem hattı, Ara Gösterim (Intermediate Representation, IR) Grafiği ve WebAssembly (Wasm) yürütme soketleri boyunca fiziksel yapılandırmalara nasıl çevrildiğini tanımlar.
Derleme işlem hattı & yürütme akışı
Aggrega, sabit kodlanmış orkestrasyon mantığı yerine katı, sabit sıralı bir Önceden Derleme (Ahead-of-Time, AOT) derleyici işlem hattı çalıştırır. aggrega build ile tetiklenen derleyici, fiziksel yapıtları oluşturmadan önce mimariyi değerlendirmek için düz grafiği yalıtılmış WebAssembly (Wasm) soketleri arasında aktarır.
Wasm soketleri gömülü bir host üzerinde — Wazero motorunun üzerindeki Extism araç seti — bir eklentinin her türlü çalışma zamanı erişim yeteneğini (ağ, dosya sistemi, duvar saati, ortam, standart G/Ç) reddeden bir AOT saflık güvenlik duvarının arkasında çalışır; böylece bir eklenti deterministik, önceden derleme garantisini bozamaz. Host, publishing-linter’ı bant dışı olarak aggrega lint aracılığıyla çalıştırır. Aşağıda açıklanan bant içi kapılar — yönetişim soketinin topoloji oluşturma sırasındaki label-transform rolü ve statik analizdeki IR-verdict rolü ile render aşamasını kapatan eklenti işlem hattı — her derlemede çalışır: bir yönetişim rolü, çalışma alanının ona bir eklenti iliştirdiği her yerde; eklenti işlem hattı ise adım bildiren her Recipe için. Her işlem hattı aşamasının durumunu Dilin durumu izler.
İşlem hattı tamamen bellek içinde, katı ve sabit bir sırayla yürütülür:
Çözümleme — Çözümleyici & sözdizimi doğrulayıcı
- Mekanizma: Kalıtım birleştirme, Go şablon enterpolasyonu ve JSON Schema 2020-12 doğrulaması.
- Eylem: CLI istenen tüm varlıkları (Components, Features, Releases) getirir. Önce bu tanımlarda
extendsanahtar sözcüğünü denetler. Katalog varlıkları için YAML meta verilerini derinlemesine birleştirir ve iki tür veri sütunlarında birbirinden ayrılır: bir Feature’ınschema:alanı JSON Schema 2020-12 bileşimi altında temelininkiyle birleşir; genişleten bir Component ise yalnızca yapıyı birleştirir — ek yuvalarını, topoloji soketlerini, kendine enjekte izin listesini ve adlandırılmış onaylamalarını — ve temelininschema:bloğunu tam olarak temelin yazdığı şekilde alır. Genişleten birReleaseaynı kurala göre katlanır: alt öğenin değeri anahtar anahtar, ilk bölünemez değere — bir skaler, bir liste, bir şablon — kadar kazanır; bu değer bütünüyle değiştirilir ve alt öğeninnullolarak yazdığı bir anahtar kaldırılır. Böylece tüm yazım yüzeyi aktarılır — bileşen başınainfrave Feature eklemeleriyle sınır ağacı,parametersbloğu, ek açıklamalar ve Manifest işaretçisi — ancak hiçbirmetadataalanı aktarılmaz, çünkü kimlik ve köken Release başınadır. Ardından üç alt adımda bellek içi bir enterpolasyon gerçekleştirir: Aggregate’in türlendirilmişparameters:bildirimlerine karşı parametre sözleşmesi doğrulaması; çözümlenmiş değerlerin çevreleyenvalues:dizelerine enterpolasyonu;.parameterseşlemesinin her değer şablonu bağlamından geri çekilmesi, böylece yalnızca operatörün yazdığı yol şablonları tarafından okunabilir kalması. Son olarak çözümlenmişinfrabloklarını hedef bileşen yüklerine enjekte eder. Plan tamamen somutlaştığında derleyici, geliştiricininvaluesveinfrayapılandırmalarını yerel olarak katı biçimde doğrulamak için Katalogdaki birleşikschema:bildirimini (kompakt biçim veya tam JSON Schema 2020-12) kullanır.- Release Feature şema doğrulaması: Release aracılığıyla eklenen Features (hem sınır genelinde hem bileşene özgü) bu adımda Katalog varlıklarına karşı çözümlenir. Derleyici, Release tarafından sağlanan
infrabloklarını katalog çözümlemesinin hemen ardından her Feature’ınschema:bildirimine karşı doğrular ve topoloji oluşturulmadan önce tür güvenliğini sağlar. - Ek açıklama güdümlü Feature genişletme alt aşaması: Manifest çözümlemesi, Recipe/Provider bağlama ve Manifest bağlama hedefi doğrulamasından (
mappings.features.annotations.<key>.mapsaltında bildirilen yolların başvurulan Feature’ınspec.schemaalanında bulunması) sonra derleyici, topoloji oluşturucudan önce bir ek açıklama genişletme alt aşaması çalıştırır. Alt aşama Release sınırlarını dıştan içe ve Aggregate alt sistemlerini dıştan içe dolaşır; bileşen başına etkin ek açıklama kümesini kademeli aktarım + geçersiz kılma + null ile devre dışı bırakma birleştirmesiyle hesaplar; her ek açıklama değerini YAML olarak bir skalere, yapılandırılmış bir değere veya null’a ayrıştırır; her değeri (skaler veya alt anahtar başına yapılandırılmış) Manifest bağlamasınınmapsbildirimi üzerinden hedef Feature şema sütununa, taraf-sütun zorlamasıyla yönlendirir (Aggregate tarafımaps.valuestetikler; Release tarafımaps.infratetikler); yaprak başına türleri Feature’ınspec.schemaalanına karşı doğrular; ve IR grafiğininorigin: annotationile işaretlediği sentetik Feature eklemeleri enjekte eder. Şemalar derleme başına bir kez derlenir ve kademeli dolaşımlar boyunca yeniden kullanılır. Genişletme, bağlama hedefi doğrulamasından sonra ve topoloji oluşturmadan önce çalışır; bu nedenle sonraki aşamalar sentetik eklemeleri yapısal olarak açık olanlarla aynı şekilde ele alır (köken incelemesi dışında). Bağlama biçimi, kademeli aktarım semantiği ve taraflar arası bileşim kuralları için bkz. 13-catalog-and-registry.md §“Ek açıklama güdümlü Feature genişletmesi” velanguage-reference/providers/well-known-annotations.md.
- Release Feature şema doğrulaması: Release aracılığıyla eklenen Features (hem sınır genelinde hem bileşene özgü) bu adımda Katalog varlıklarına karşı çözümlenir. Derleyici, Release tarafından sağlanan
Topoloji oluşturma — Topoloji oluşturucu & mutasyon kapısı
- Mekanizma: AST genişletme + yönetişim soketinin
label-transformrolü. - Eylem: Derleyici, grafikteki düğümler arasında deterministik olarak topolojik kenarlar çizmek için doğrulanmış bileşenlerden açıkça bildirilmiş
usesbloklarını yerel olarak okur vevaluesbloğunu tamamen opak bırakır. Ardından Mutasyon Kapısı’nı değerlendirir; grafiğin bir izdüşümünü — her düğümün etiketleri ve örneğinin bildirdiği, derleyicinin okumadan aktardığıvalues— Release’in adı ve ortamıyla birliktelabel-transformrolüne eklenmiş bir yönetişim eklentisine aktarır. Eklenti bağlamı değerlendirir ve grafiği dinamik olarak otomatik etiketlemek için JSONPatch’ler döndürür (ör. Release’in ortamına dayanarakcompliance.aggrega.ai/data-class: restrictedetiketini veya bir veritabanının bildirdiği uzantılara dayanarakdatastore.aggrega.ai/engine: vectoretiketini enjekte etmek); yamalar yalnızca etiketlere ulaşır.
Grafiğin sonlandırılması
- Mekanizma: Normalleştirme.
- Eylem: Derleyici düz Ara Gösterim (IR) Grafiğini sonlandırır ve topoloji oluşturucunun çizdiği açık topolojik kenarları korur. Ardından eklenmiş Features ile bunların
valuesyüklerini düğüm kimliğine göre eşlenmiş düz bir sözlüğe normalleştirir ve yetenekten bağımsız grafiği doğrulamaya hazırlar.- IR yük normalleştirmesi: IR’nin yapısal biçimi, yapılandırma için Tek Doğruluk Kaynağı ilkesini zorunlu kılar: topoloji katmanı yalnızca grafik yapısını (düğüm kimliği, kenarlar, meta veri etiketleri) taşır ve normalleştirilmiş yapılandırma durumu, derleyicinin sonraki eklentilere aktardığı ayrı bir bellek içi sözlükte yaşar. Yapılandırmayı değiştiren mutatörler onu tek bir yerde değiştirir; sağlayıcı, normalleştirilmiş durumu gereksiz depolamadan kaynaklanan sapma riski olmadan okur.
Statik analiz — Statik analizci & doğrulama kapısı
- Mekanizma: Topolojik saflık denetimleri + yönetişim soketinin
ir-verdictrolü. - Eylem: Derleyici IR Grafiği üzerinde soyut statik analiz çalıştırır. İlk olarak
usesSchematanımlarındanselectordizelerini çıkarır ve bildirilmiş soketler üzerinde düğümler arası tür güvenliğini garanti etmek için bunları, açıkça tanımlanmış grafik kenarları boyunca yerel bir Go etiket eşleştirme motoruyla (Kubernetes tarzıAND,in()aracılığıylaORve!=aracılığıylaNOTsemantiğini destekleyen) değerlendirir. Geçici bir soketteki kenarın — bir Aggregate yazarının adlandırdığı ve kataloğun bildirmediği bir soket — katalog girdisi ve dolayısıyla seçicisi yoktur; bu yüzden bu denetimin değerlendireceği bir şey de, eksik olan bir şey de yoktur; her kenar ikisinden hangisi olduğunu kaydeder ve geçici bir kenarın ne taşıyabileceği bunun yerine hedefin bildirilmişprovidesalanıyla sınırlanır. Ayrıca eklenmiş özelliklerin hedef bileşenlerinin etiketleriyle uyumlu olduğunu doğrulamak için FeatureappliesToveappliesToAnyOfseçicilerini, her doldurulmuş ek yuvasının kendiselectoralanını da onu dolduran Feature’ın etiketlerine karşı değerlendirir. İkinci olarak, bir düğümün Component’inin bildirdiği her varlık zorunluluğunu — herfeatures.aggrega.ai/requiredType.<label>ek açıklamasını — o düğümün nihai ek kümesine karşı değerlendirir. Bu denetimin yeri analizcidir, çünkü kuralın iki yarısını birden tutan ilk aşama odur: çözümlenmiş Component varlığının ek açıklamaları ve 5 Katmanlı kademenin ürettiği ek kümesi; Aggregate’e eklenen, alt sisteme eklenen, Release’e eklenen ve ek açıklamayla genişletilen eklemeler aynı şekilde sayılır. Hiçbir eklemenin karşılamadığı bir zorunluluk derlemeyi durdurur; bildirimi hatalı biçimlendirilmiş bir zorunluluk ise ayrı bir tanılamayla durdurur, böylece bozuk bir bildirim hiçbir zaman karşılanmış bir gereklilik gibi okunmaz. Üçüncü olarak Doğrulama Kapısı’nı yürütür; tam grafik yapısını (tüm düğümler, kenarlar, eklenmiş özellikler ve önceden hesaplanmış DFS yolları dahil)ir-verdictrolüne eklenmiş bir yönetişim eklentisine aktarır. Kuruluşun özel Wasm ilkesi topolojiyi değerlendirir. Wasm eklentisi bir hata dizisi döndürürse (ör. belirli bir proxy özelliği olmadan birpublicdüğümden birrestricteddüğüme kesintisiz bir yol tespit ederse), derleme durur.
Render aşaması
- Mekanizma: Render öncesi yakalama (
injectMapping), geç bağlama (valuesMapping) ve Wasm render soketleri (pipeline). - Eylem: Son yapıt üretim aşaması, sabit bir sırayla çalışan katı zamansal alt aşamalara bölünür; bu da yürütmeyi deterministik tutar:
- Inject eşleme (render öncesi yakalama): Go derleyicisi Geliştiricinin soyut
.context.injectsözleşmesini çözümler. Ardından eklenmiş tümFeatureRecipesiçindekiinjectMappingGo şablonlarını katı 5 Katmanlı Soğan Modeli yürütme sırasına göre yürütür (Alt Aggregate — önce bir modül bileşeninin kendi eklemeleri, ardından modülünün alt sistemlerinin bildirdikleri, dıştan içe → Kök Aggregate bileşeni → Kök Aggregate alt sistemi → Release sınırı dıştan içe → Release bileşene özgü). Derleyici ortaya çıkan sözlükleri Çağıranın.context.injectbellek borusunun üzerine yerel olarak derinlemesine birleştirir. Bu, Temel Recipe bunları görmeden önce Çağıran için ortam değişkenlerini ve bağlantı dizelerini güvenli biçimde yeniden yazar. Bir eşleme, Çağıranın kendiinject:bloğunun veya bağlantılarından birinin sağladığını yeniden yazabilir; farklı bir eklenmiş Feature’ın zaten sağladığı bir anahtar — kendi eşlemesi veya kendiinject:bloğu aracılığıyla — her iki eklemeyi adlandırarak derlemeyi durdurur; böylece yürütme sırası hiçbir zaman iki eklemenin değerleri arasında karar vermez. - Locals ön bölümü: Herhangi bir
providesşablonu çalışmadan önce derleyici, Recipe’nin.localsgirdilerini yazıldıkları sırayla, her birini kendi içinde bütünlüklü, düğüme yerel bir bağlama karşı değerlendirir —.context.instance_id,.values,.infrave aynı bloğun o ana kadar çözümlenmiş girdileri; ancak.context.injectveya.context.usesdeğil. Bu nedenle bir girdi, üstünde tanımlanmış bir kardeşi okuyabilir ve o kardeşin çözümlenmiş değerini alır; bir girdinin diğerini okuduğu her yerde yazım sırası sözleşmenin parçasıdır ve bir başvurunun çözümlenmesi için blok hiçbir zaman yeniden sıralanmaz. Önce locals’ın çözümlenmesi, birprovidesşablonunun.localsokuyabilmesini sağlar. Recipe’nin.sourceşablonu, bu locals çözümlendikten sonra aynı bağlama karşı değerlendirilir; bu da.localsalanını bir Recipe’nin şablonları boyunca kısaltma olarak yeniden kullanılabilir tutar ve yazarların.sourcealanını (chart sürümü, yol, kayıt defteri) sınır başına parametrelendirmesine olanak tanır. - Temel render (temel Recipe
valuesMapping): Derleyici Temel Recipe’ninvaluesMappingşablonunu değerlendirir. Şablon, yakalanan dizeleri.context.injectborusundan okur (inject eşleme sırasında yeniden yazılmış) ve ortaya çıkan değerler sözlüğü, temel altyapı yapıtlarını render etmek için Recipe’nincapabilityalanının adlandırdığı sağlayıcıya verilir — helm ve helm-chart sağlayıcılarının ikisi de Helm üzerinden render eder. - Workload ayrıştırma ve doğrulama:
workload:bildiren bir Recipe’de — satır içi blok içeriği veya bir dosyayı adlandıranworkload: { $import: <path> }— bu belge düğümün render bağlamına karşı bir şablon olarak değerlendirilir, ardından YAML olarak Workload biçimine ayrıştırılır ve denetlenir: render edilen baytlar Workload şemasına karşı doğrulanır, çözülen değer de ona karşı doğrulanır (baytlar çözmenin attığı anahtarları taşır ve çözme boş verilen bir alanı atlar; bu yüzden her biri diğerinin göremediğini reddeder), herattachmentsgirdisi bağlı Component’infeaturesSchemaalanının bildirdiği yuvalara karşı denetlenir ve her kaynak başvurusu adlandırdığı yuvanın çözümlenmişprovidesalanına karşı denetlenir. Buradaki bir hata derlemeyi durdurur. Ayrıştırılan Workload şablon bağlamına.workloadolarak yerleştirilir; böylece aynı düğümde daha sonra değerlendirilen bir şablon onu okuyabilir. - Yapıt değerlendirmesi: Bir Recipe’nin
artifacts:altında bildirdiği her girdi — satır içi içerik veya o girdinin kendi$import:alanıyla adlandırılan bir dosya — okunur, şablon olarak ayrıştırılır, tam şablon bağlamına karşı değerlendirilir ve derlemenin kökenini taşır. Ortaya çıkan izdüşüm sağlayıcıya verilir; çıktı biçimine, kökenin nereye yerleşeceğine, çıktı yoluna ve nihai baytlara sağlayıcı karar verir. Üretilen her dosya hangi yazım biçiminden geldiğini kaydeder; böylece bir dosya adı çakışması katkıda bulunan herkesi adlandırabilir. - Workload sentezi: Ayrıştırılan Workload, Recipe’nin
capabilityalanının adlandırdığı sağlayıcıya verilir ve sağlayıcı onu kendi yerel kaynaklarına çevirir.workload:bildirmeyen bir Recipe’nin burada sentezleyecek bir şeyi yoktur; dosyaları bunun yerine kaynak render işleminden gelir. - Feature render (FeatureRecipe kaynak üretimi): Düğüm üzerindeki, bağlı FeatureRecipe’si kendi
source,workload,artifactsve/veyavaluesMappingalanını taşıyan her ekleme — bir ServiceMonitor, bir NetworkPolicy, bir sidecar ConfigMap veya bir kimlik bilgisi teslim kaynağı gibi yardımcı manifestler için kullanılan Kaynak Üretimi deseni — inject eşlemenin izlediği aynı 5 Katmanlı Soğan Modeli sırasıyla tek geçişte değerlendirilir. Tek bir ekleme kümesi üzerinde tek bir sıra vardır: operasyonel bir Feature ile bir kimlik bilgisi Feature’ı aynı yolu izler ve aralarındaki fark, her birinin FeatureRecipe’sinin ne ürettiğidir. Her eklemenin.valuesve.infraalanları kendi kapsamına çevrilir; ekleme, temel Recipe’nin değerlendirilmiş.localsalanını devralır;.attachment_namerender edilen örneği adlandırır ve.provideseklemenin kendi çözümlenmiş provides değerlerini, yani tüketicinin okuduğu aynı torbayı taşır. Ortaya çıkan değerler sözlüğü FeatureRecipe’nin kendi capability’sinin adlandırdığı sağlayıcıya verilir ve render edilen dosyalar sınırın çıktısına iki koordinat taşıyarak eklenir — Feature’ın eklendiği bileşen, ardından eklendiği ad — böylece birkaç bileşene eklenmiş tek bir Feature adı her birini ayrı tutar. Bu koordinatların hangi biçimi alacağı host sağlayıcının kendi düzeninden çıkar: hedefin her katkıda bulunana kendi konumunu verdiği yerde bileşenin kendi dizininin yanında bir<component>--<instance>/dizini, hedefin yalnızca doğrudan bir dizinde duran dosyaları okuduğu yerde ise bir<component>--<instance>--dosya adı öneki. Yalnızca inject yapan FeatureRecipes — yalnızcainjectMappingtaşıyanlar, inject eşleme sırasında zaten işlenmiş olanlar — burada atlanır. Önceki alt aşamalar gibi özellik render aşaması da her seferinde bir bileşen için çalışır; bu yüzden bir ekleme normalde eklendiği bileşenden hemen sonra değerlendirilir. FeatureRecipe’sireadsCallerRenderFacts: trueveyareadsTargetRenderFacts: truebildiren bir ekleme ise her bileşen ve ikisini de bildirmeyen her ekleme render edildikten sonra değerlendirilir — böylece host’una bağlanan her bileşen ve host’unun bağlandığı her bileşen o zamana kadar render edilmiş olur — ve çıktısı aksi halde yerleşeceği yere yerleşir. - Eklenti işlem hattı (Wasm adım yürütme): Derleyici Recipe’nin
pipelinedizisini okur ve adımlarını bildirildikleri sırayla yürütür. Her adımın adlandırılmış Wasm eklentisini düğümün render edilmiş belgelerine karşı çalıştırır, adımın döndürdüğü RFC 6902 JSON Patch işlemlerini bu işlemlerin hedeflediği belgelere uygular ve adımın yan etkilerini bunların yanında üretir — bir Envoy sidecar enjekte etmek veya bir secret VolumeMount bağlamak gibi cerrahi mutasyonların arkasındaki yüzey budur.when:kapısı yanlış değerli (falsy) render edilen bir adım geçiş olarak atlanır ve belge kümesi sonraki adım için değişmeden kalır. Her adımınpluginURI’si, yürütmeden önce kilit dosyasının özetle sabitlediği doğrulanmış yapıt baytlarına çözümlenir. Bir FeatureRecipe’ninpipelineadımları da aynı şekilde, eklemenin kendi render edilmiş belgeleri üzerinde ve bileşen kapsamlı bir ekleme için bunların yanında host bileşeninkiler üzerinde yürütülür.
- Inject eşleme (render öncesi yakalama): Go derleyicisi Geliştiricinin soyut
Üç Recipe girdi türünün üçü de derleyiciye ulaşır: source: + valuesMapping: temel render aracılığıyla, workload: iş yükü ayrıştırma ve iş yükü sentezi aracılığıyla, artifacts: ise yapıt değerlendirmesi aracılığıyla. Belirli bir sağlayıcıya bunlardan hangisinin verilebileceğine alt aşama alt aşama karar verilmez — bu, herhangi bir render gönderiminden önce, sağlayıcının kendi bildirdiği sözleşmeden, düğüm başına bir kez belirlenir; böylece girdi türünü bağlı sağlayıcının kabul etmediği bir Recipe render işleminin ortasında değil, orada reddedilir. Üç girdi türü bileşim modeli, Workload türü ve Artifacts mekanizması için bkz. 16-recipe-input-composition.md; hangi sağlayıcının hangi türü kabul ettiği için bkz. Dilin durumu.
GitOps’a özgü çıktı
Çıktısının nasıl uygulandığı konusunda kesinlikle kendi görüşü olmayan bir yapıda kalmak için render eklentileri, üretilen yapıtları temiz, sınırlara göre yalıtılmış bir dizin yapısına yazar (ör. dist/boundaries/aws-core-cluster/, dist/boundaries/gcp-data-cluster/). Bu, harici GitOps denetleyicilerinin (ArgoCD veya Flux gibi) altyapıyı eşitleyip uygulamasına olanak tanır; Aggrega derleyicisinin canlı küme API kimlik bilgilerine hiçbir zaman ihtiyacı olmaz.
graph TD
subgraph CLI_Orchestrator ["The Aggrega Compiler Pipeline"]
direction TB
A["Resolution — The Resolver & Syntax Validator<br/>(Inheritance Merge + Parameter Interpolation + JSON Schema 2020-12 Validation)"] --> B["Topology construction — The Topology Builder<br/>(AST Expansion + governance label-transform)"]
B -->|"Emits IR Graph"| C["Graph finalization<br/>(Normalization)"]
C -->|"Flat IR Graph"| D["Static analysis — The Static Analyzer<br/>(Selectors + governance ir-verdict Gate)"]
D -->|"Validated Topology"| E["Rendering<br/>Inject mapping: Pre-Render Interception (injectMapping)<br/>Base rendering (valuesMapping)<br/>The plugin pipeline: Wasm Mutation (pipeline)"]
end
graph LR
E["Rendering"]
E -->|"Stringified Artifacts"| F["Helm Charts"]
E -->|"Stringified Artifacts"| G["Docker Compose"]
E -->|"Stringified Artifacts"| H["Kubernetes Manifests"]
E -->|"Stringified Artifacts"| I["Terraform Configuration"]
E -->|"Stringified Artifacts"| J["CloudFormation Templates"]
Altyapı kaynak haritası
Aggrega, ~30 satırlık bir Aggregate.yaml dosyasını binlerce satırlık fiziksel JSON veya YAML yapılandırmasına derler. Çalışan bir kaynağı kaynağına kadar izlemenin bir yolu olmadan, “main.tf.json satır 4.032” konumundaki bir hatayı ayıklamak geliştiricileri eşlemeyi elle yeniden kurmaya zorlar. Aggrega’nın render eklentileri bunu, izleme tanımlayıcılarını sağlayıcının yerel meta veri yüzeyine — Kubernetes için metadata.labels ve metadata.annotations, Terraform için bir köken yorumu ve sağlayıcı başına eşdeğer uzlaşımlar — birleştirerek ele alır; böylece render edilen her nesne geldiği kaynağa geri işaret eden bir işaretçi taşır. aggrega.ai/compiler-version etiketi (governance-and-compliance §5 içinde belgelenmiştir) bu ailedeki izleme anahtarlarından biridir; damga onun yanında aggrega.ai/aggregate-name, aggrega.ai/component-id, aggrega.ai/boundary-path, aggrega.ai/recipe-uri ve aggrega.ai/environment anahtarlarını taşır ve helm, helm-chart, compose, terraform ve cloudformation sağlayıcılarının her biri onu üretir — helm-chart sağlayıcısı, chart’ın kendi şablonlarını değiştirmeden kopyaladığı için bir Recipe’nin chart’a eklediği şablon dosyalarında.
Damga, özelliğin kökenini veya katalog türünü tanımlayan hiçbir anahtar taşımaz.
Derleyiciyle birlikte iki hata ayıklama yüzeyi daha gelir. aggrega build --trace, her aşamanın ne aldığını ve ne ürettiğini inceleyen bir Recipe yazarı için her düğümün ara durumunu geçiş geçiş .trace/ dizinine (dist/ yanında) yazar; ve derlemeyi durduran bir tanılama, hatanın ait olduğu bir yazım yüzeyi varsa o yüzeyin kategorisini — DEVELOPER_ERROR, OPS_ERROR, CATALOG_ERROR ve diğerleri — taşır; böylece doğru yazarı gösterir. Başarısız olan üretilmiş bir manifest alanını onu üreten şablon satırına kadar izleyen hatalar derleyicinin parçası değildir.
Doğrulayıcı işlem hattı
Çözümlemenin şema doğrulama aşaması, varlık spesifikasyonu içeriğini (kompakt biçim, JSON Schema YAML’ı veya karışık) yaprak başına köken bilgisi taşıyan birleşik bir JSON Schema 2020-12 belgesine dönüştüren ve ardından geliştiricilerin yazdığı örnek içeriğini buna göre doğrulayan bir doğrulayıcı işlem hattına dayanır. Beş evre sırayla saf dönüşümler olarak çalışır; her biri, bildirilen girdileri üzerinde deterministik bir fonksiyondur.
Evre 1 — Kompakt biçim derlemesi. Derleyici schema:, parameters: ve SchemaLibrary içeriğinin YAML ağacını dolaşır; düğüm başına yönlendirme yapar (kompakt biçim yaprağı, JSON Schema YAML’ı, $ref: başvurusu ya da bileşim); çözümlenmiş JSON Schema 2020-12 üretir. Kompakt biçim ve JSON Schema YAML’ı, $jsonschema: kaçışı aracılığıyla herhangi bir düğüm sınırında karışabilir; derleyici karışık durumu ağacı dolaşıp düğüm başına yönlendirme yaparak ele alır. Dönüşüm saf bir fonksiyondur: aynı kompakt biçim girdisi her zaman aynı JSON Schema çıktısını üretir. Anahtar sözcük dağarcığı için language-reference/vocabulary/compact-form-authoring.md sayfasına bakın.
Evre 2 — spec.templates ve $instantiate: çözümlemesi. Şablon başvurusu olarak yazılmış SchemaLibrary girdileri için derleyici, $instantiate:’i $args: ile çağıran her kitaplık girdisini dolaşır, parametre değerlerini değişmez skaler yerine koyma olarak yerleştirir ve somut şema girdileri üretir. Yerine koyma, kitaplığın her yüklenişinde bir kez çalışır; çözümlenmiş girdiler önbelleğe alınır. Kitaplık varlığının yazım biçimi için language-reference/entities/schemalibrary.md sayfasına bakın.
Evre 3 — Belgeler arası $ref: genişletmesi. $ref: aracılığıyla yapılan SchemaLibrary başvuruları için (kimlik biçimi <Library>#/schemas/<entry>), derleyici başvuru zincirini derleme zamanında bir çözümleme yığını taşıyarak dolaşır; başvurulan içerik tüketicinin şemasına satır içi yerleştirilir. Genişletme; döngü algılamayı (döngüler derlemeyi zinciri adlandıran bir hatayla durdurur), konum değil kimlik korumasını (registry ana bilgisayarı içeren bir başvuru derlemeyi durdurur ve kimlik biçimine yönlendirir — başvurular kitaplıkları fiziksel konumla değil kimlikle adresler) ve tek kaynaklı bileşimi ($ref: blokları yalnızca çıplak başvuruyu kabul eder; tüketici tarafı geçersiz kılmalar JSON Schema’nın allOf:’u ile birleştirilir) korur. Çözümleme anlambilimi için language-reference/vocabulary/cross-document-ref.md sayfasına bakın.
Evre 4 — featuresSchema: için köprü sentezi. Derleyici her varlığın featuresSchema: içeriğini yazar sırasıyla dolaşır ve her ek yuvasını bağlayabilecek bir dolgunun yapısını tanımlayan bir JSON Schema parçası üretir; inject izin listesi bildiren bir yuvaya x-aggrega-inject: uzantı anahtar sözcüğü eklenir. Bu parça, geliştiriciye dönük schema: içeriğine katılmak yerine yazılmış ek bloğuna karşı kendi başına derlenir ve denetlenir; uzantı anahtar sözcüğü, JSON Schema doğrulamasının yok saydığı bir meta veridir ve sonraki hiçbir evre onu parçadan geri okumaz — bir yuvanın izin listesine ihtiyaç duyan bir denetim yuvayı okur. usesSchema: soket tablosu hiçbir parçaya yansıtılmaz: bir soketin selector: ve inject: değerleri Mimar’ın yazdığı türlendirilmiş YAML olarak okunur ve bir soketin kenar başına valueSchema: / infraSchema: değeri kendi başına derlenir. Sentez, girdileri üzerinde saf bir fonksiyondur.
Evre 5 — Köken bilgili özel birleştirici. extends: bildiren varlıklar için derleyici üst zinciri dolaşır; üst varlığın çözümlenmiş JSON Schema’sı temel olur; alt varlığın geçersiz kılmaları bunun üzerine uygulanır. Çözümlenmiş şemadaki her yaprak, yaprak başına bir köken etiketi taşır (dosya yolu, satır numarası, üst veya alt kaynaklı olduğu). Birleştiricinin çıktısı doğrulayıcı motorun tükettiği şeydir; doğrulayıcı motor, değiştirilmemiş üçüncü taraf bir JSON Schema 2020-12 uyumlu uygulamadır ve bulguları sıralı üretmek için etrafında deterministik bir gezgin bulunur.
Beş evre, doğrulayıcı motor şemayı görmeden önce çalışır. Motor tek bir çözümlenmiş JSON Schema 2020-12 belgesi ile geliştiricinin örnek içeriğini alır; bir doğrulama raporu üretir. Hata biçimlendirici, kaynak konumlarını açıkça adlandıran kullanıcıya dönük tanılamalar üretmek için köken etiketlerine başvurur — bir Feature’ın kendisi yazmak yerine tabanından devraldığı bir kısıtın kaynak dosyası da buna dahildir.
Doğrulayıcı işlem hattı, her yükün ilk kez tamamlandığı yerde çalışır — çözümleme sırasında bir bileşenin values ve infra alanları, topoloji oluşturma onları dahil ettiğinde bir alt aggregate’in bileşenleri ve grafik sonlandırılırken bir eklemenin yükü — böylece bir şema bulgusu, statik analiz herhangi bir seçiciyi değerlendirmeden önce ve doğrulama ifadesi değerlendirmesinden önce derlemeyi durdurur; bu da doğrulama ifadesi şablonlarının doğrulanmış yüklere güvenmesini sağlar.
İşlem hattı boyunca determinizmin korunması
Derleme işlem hattının her evresi Deterministik Çıktı Değişmezini korur: aynı kaynak dosyalar, aynı kilit dosyası ve aynı derleyici sürümü verildiğinde, derleme bayt bayt aynı çıktıyı üretir. Değişmez temeldir — kilit dosyasında içerik adreslemesi kararlı yapıt özetleri gerektirir; yeniden üretilebilir derlemeler, geliştirici A’nın dizüstü bilgisayarında yazılan bir sürümün geliştirici B’nin dizüstü bilgisayarında ve CI’da aynı çıktıya derlenmesini gerektirir; fark incelenebilirliği, kaynak değişikliklerinin derlenmiş çıktıdaki tek değişiklikler olarak görünmesini gerektirir.
Determinizm, her dönüşümün uyduğu az sayıda disiplinle korunur:
- Sabit yineleme sırası. Harita biçimli YAML üzerindeki her dolaşma sabit bir sırayla yinelenir, çünkü Go’nun yerel harita yinelemesi rastgeledir. Derleyici çoğu evrede yinelemeden önce sıralar (kompakt biçim derleyicisi, birleştirici,
spec.templatesçözümleyicisi, hata biçimlendirici, YAML serileştirici); ek yuvası izdüşümü ise yazarın kendi sırasını korur, böylece bir yuva tablosunun özellik sırası yazıldığı sıradır. - Zaman gömme yok. Derleme, çıktıya zaman damgası gömmez. Saat 14:00’teki bir derleme, saat 02:00’deki bir derlemeyle aynı yapıtı üretir. Birleştiricinin köken meta verisi dosya:zaman damgası değil, dosya:satır kullanır.
- Çalışma alanına göreli yollar. Çözümlenmiş çıktıdaki tüm yollar çalışma alanına görelidir; yol çözümleme katmanı, yollar herhangi bir çıktıya girmeden önce onları normalleştirir.
- Rastgele kaynak yok, harici durum yok. Dönüşümler, bildirilen girdileri (varlık içeriği, üst zincir, kilit dosyası) üzerinde saf fonksiyonlardır. Harici duruma yalnızca çözümleme sırasında (OCI yapıtlarının getirilmesi) başvurulur ve çözümlenmiş içerik özetle içerik adreslidir.
- Kanonik YAML serileştirmesi. Çıktı, bir girdi için tek bir sabit biçimde yazılır: her çalıştırmada her derinlikte aynı anahtar sırası, diziler ve
enum:dizileri girdi sırasında; 2 boşluklu girinti; Unix LF satır sonları; YAML’ın izin verdiği yerlerde tırnaksız dizeler;true/falsemantıksal biçimi; bulunmayan alanlar için null atlanır. $defs:alfabetik sırası. Şema$defs:girdileri, çözümlenmiş JSON Schema’da alfabetik anahtar sırasıyla üretilir.$defs:kavramsal olarak sıralı bir liste değil, bir sözlüktür; alfabetik sıra, kaynağın yeniden düzenlenmesi boyunca farkları öngörülebilir kılar.- Paralellik çıktıya yansımaz. Derleyici bağımsız birimleri paralelleştirebilir (farklı varlıklar eşzamanlı derlenebilir). Paralel sonuçlar serileştirilmeden önce deterministik bir yapıda toplanır (ör. varlık adına göre sıralanmış).
Derleyicinin uçtan uca testleri, her fikstürü tek bir test içinde birkaç kez derler ve her çalıştırmanın bayt düzeyinde aynı içeriğe sahip aynı dosyaları ürettiğini doğrular. Bir harita yineleme sırası sızıntısını veya sıralanmamış bir küme üzerindeki yinelemeyi yakalayan şey derlemenin tekrarlanmasıdır; bunlar çoğu çalıştırmada kararlı çıktı verir ve ara sıra ayrışır. Testler derleyicinin geri kalan test paketiyle birlikte çalışır.
Deterministik Çıktı Değişmezi derleme zamanında geçerlidir: aynı kaynak dosyalar + aynı kilit dosyası + aynı derleyici sürümü verildiğinde bayt bayt aynı çıktı. Kilitleme zamanındaki eşlik eden özellik (aynı kaynak dosyalar + aynı registry durumu verildiğinde aynı kilit dosyası) daha zayıftır — registry’ler değişkendir (yeni sürümler yayımlanabilir; yan araçlar eklenebilir; bileşen başına meta veriler değişebilir), bu nedenle aynı kaynak dosyalara karşı farklı zamanlarda yapılan iki kilitleme çağrısı farklı kilit dosyaları üretebilir. npm, Cargo ve Go’daki uzlaşımları yansıtan kilit dosyasının amacı da budur. Yeni bir kilit dosyasından derleme deterministik çıktı üretir. İki anın ayrılması, registry tarafındaki değişkenliği katlanılabilir kılan şeydir: T2 zamanında yayımlanan bir yan araç bir sonraki kilitleme çağrısını değiştirir; T1 zamanında üretilen kilit dosyasına karşı yapılan derlemeleri değiştirmez.