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

Kimsenin bildirmediği, gerçek değerler ileten bir soket

Bu örnek tek bir satırı ve onun iki yarısını da öğretir:

Bir tüketici bağlantıyı kendisi icat edebilir. Yalnızca üreticinin bildirdiğini tüketebilir.

Bir Aggregate yazarı, kendi bileşeni üzerinde hiçbir katalog varlığının bildirmediği bir soket adı altında bir uses: girdisi yazar. Kenar oluşturulur ve değer iletir; değer, işlenen yapıta tam olarak bildirilmiş bir soket üzerinden ulaşacağı gibi ulaşır. Ancak o kenarın taşıyabileceği anahtarları bildirmek hâlâ hedefe aittir: hedefin bildirmediği bir anahtar adlandırırsanız derleme durur.

Buradaki her şey standart kütüphane kataloğundan çözümlenir. Çalışma alanı kendine ait hiçbir Component, Feature veya Recipe yazmaz.

Yığın

Üç bileşen var ve bunlardan biri iki farklı şekilde bağlanır:

örnektürne olduğu
dbcore/datastore/mariadbveritabanı
modelcore/ai-model/anthropicbir model uç noktası; başvuru biçimli bir gerçekleştirme, bu yüzden onun için hiçbir hesaplama çalışmaz
webcore/devtool/adminerikisini de tüketen konsol

core/devtool/adminer tam olarak bir soket bildirir:

usesSchema:
databases:
selector: "component.aggrega.ai/type=stateful-server"
inject: [env]

Yazarının öngördüğü şeyin tamamı budur. Bir veritabanının önünde duran bir konsol onların aklındaki bağlantıdır; ortamında bir model uç noktası taşıyan bir konsol ise değildir.

Aggregate’in yazdıkları

aggregate-delivers.yaml, iki kenarı da tek bir uses: bloğundan bağlar:

web:
type: core/devtool/adminer
uses:
databases: # DECLARED — the socket the Component's usesSchema names
db:
target: db
inject:
env:
- in: ADMINER_DEFAULT_SERVER
from: host
assistant: # AD-HOC — declared nowhere
model:
target: model
inject:
env:
- in: ASSISTANT_ENDPOINT
from: endpoint
- in: ASSISTANT_MODEL
from: model

assistant, ne bu Component’te ne de başka birinde hiçbir usesSchema içinde geçmez. Yine de geçerlidir: kataloğun bir soket hakkında sessiz kalması, bağlantının öngörülmediği anlamına gelir, yasaklandığı anlamına gelmez; ve geliştirici kendi uygulamasının topolojisinin sahibidir.

Geçici soketin vazgeçtiği şey, eksik usesSchema girdisinin taşıyacağı şeyin ta kendisidir: selector yoktur, bu yüzden kenarın hangi bileşene ulaşabileceğini hiçbir şey kısıtlamaz ve düğümler arası tür güvenliği denetiminin değerlendireceği bir şey kalmaz; inject: izin listesi yoktur; kenar başına valueSchema veya infraSchema yoktur, bu yüzden kenar başına values: ve infra: için denetlenecekleri bir sözleşme ve devralınacak bildirilmiş varsayılanlar yoktur. Böyle bir sokete yazılan kenar başına yapılandırma kabul edilir ve denetlenmeden taşınır; o katman için sözleşmesi olmayan her soket böyle davranır: hiç valueSchema yazmayan bildirilmiş bir soket de aynı durumdadır.

Vazgeçmediği şey ise kenarın ne taşıyabileceğidir. endpoint ve model, core/ai-model/anthropic’in provides katmanında bildirdiği anahtarlardır.

Örneği oluşturun

Bu örneği aşağıdaki komutlarla derleyebilir ya da yapay zekâ asistanınıza sizin için derletebilirsiniz.

Örneği, adını taşıyan yeni bir klasöre yazın:

Terminal window
aggrega scaffold --example adhoc-uses-socket

Ardından sırada çalıştırılacak komutları yazdırır. İlki yeni klasöre geçer:

Terminal window
cd adhoc-uses-socket

Derleme

Terminal window
aggrega build --release release-delivers.yaml --auto-pull

İşlenen çıktı ve kilit dosyası üretilir, birlikte dağıtılmaz: bu örnek girdilerini işler ve geri kalan her şeyi yeniden üretir. --auto-pull, kilit dosyasını derleme sırasında çözümler; önceden bir kez aggrega pull --release release-delivers.yaml çalıştırmak aynı işi yapar ve sonraki derlemelerin hiç bayrak olmadan çalışmasını sağlar. Katalog varlıkları, .aggrega-config.yaml dosyasının adlandırdığı varsayılan kayıt defteri olan hub.aggrega.ai’den çözümlenir; bu nedenle ne derleme ne de aggrega inspect bir --catalog bayrağına ihtiyaç duyar.

Bir yapay zekâ asistanıyla

Aggrega araçlarıyla kurulmuş bir yapay zekâ asistanı da aynısını yapabilir: bu istemi ona yapıştırın.

Yalnızca Aggrega araçlarını kullanın ve kendiniz hiçbir klasör oluşturmayın. Çalışma alanı klasöründe henüz `adhoc-uses-socket` klasörü yoksa `scaffold` aracını `example` değeri `adhoc-uses-socket` olarak ayarlanmış ve `dir` olmadan bir kez çağırın: örneği yeni bir `adhoc-uses-socket` klasörüne yazar. Ardından `build` aracını `workspace_root` değeri `adhoc-uses-socket`, `release` değeri `release-delivers.yaml`, `auto_pull` değeri true ve `write` değeri true olarak ayarlanmış şekilde çağırın. Derlemenin hangi dosyaları yazdığını bana söyleyin; dosyalar `adhoc-uses-socket/dist/` altındadır.

Çıktıyı okuyun

dist/compose/docker-compose.yaml, web hizmeti:

web:
image: adminer:4
environment:
ADMINER_DESIGN: pepa-linha-dark
ADMINER_DEFAULT_SERVER: db
ASSISTANT_ENDPOINT: https://api.anthropic.com
ASSISTANT_MODEL: claude-sonnet-4-5
[… omitted: the service's ports, provenance labels, networks, depends_on and healthcheck]

Dört değişken, bunlardan üçü kenarlar üzerinden iletilmiş ve çıktı hangi soketin bildirilmiş olduğunu kaydetmez:

  • ADMINER_DEFAULT_SERVER: db, bildirilmiş soket olan databases üzerinden geldi. Değeri, veritabanı Recipe’inin provides.host değeridir: bir Compose hizmet adı.
  • ASSISTANT_ENDPOINT ve ASSISTANT_MODEL, geçici soket olan assistant üzerinden geldi ve model Recipe’inin provides.endpoint ve provides.model değerlerini taşıyor.

Hepsi tek bir eşlemede, yazar sırasıyla durur; aralarında hiçbir işaret, hiçbir açıklama ve hiçbir sıralama farkı yoktur. Asıl mesele budur: geçici bir soket bildirilmesi açısından farklı bir şeydir, iletilmesi açısından değil. Tek bir iletim yolu vardır ve iki kenar da onu kullanır.

ASSISTANT_ENDPOINT aynı zamanda bir önceden derleme (ahead-of-time) olgusu olarak da okunmaya değer. Derleyici https://api.anthropic.com adresini keşfetmek için Anthropic ile iletişim kurmadı; Recipe bunu, model bileşeninin infra.endpoint değerinden kaynaklanan deterministik bir işaretçi dizesi olarak üretti ve derleyici bu dizeyi yorumlamadan yönlendirdi. Adminer’ın kendisi ASSISTANT_* değişkenlerinin hiçbirini okumaz; bu iletim anahtarlarını geliştirici seçti ve konsolun kapsayıcısı onları orada kim okuyacaksa onun için taşır.

Derlemenin ürettiği grafik, işlenen yapıt kaydetmese de bu ayrımı kaydeder: her kenar declared veya ad-hoc değerini taşıyan bir socket_declaration alanı içerir, böylece her bağlantının kendi Mimarlarının bildirdiği bir soketten geçmesini isteyen bir kuruluş bunu, derleyicinin bir görüş sahibi olmasına güvenmek yerine bir yönetişim politikası olarak ifade eder. Bkz. architecture/11-governance-and-compliance.md.

Kontrol: tüketicinin hâlâ icat edemeyeceği şey

aggregate-undeclared-key.yaml, tek bir düzenlemeyle aggregate-delivers.yaml dosyasıdır. Geçici kenar üçüncü bir anahtar ister:

- in: ASSISTANT_API_KEY
from: api_key

core/ai-model/anthropic, provides katmanında endpoint ve model anahtarlarını bildirir, başka hiçbir şeyi değil. Derlemenin başarısız olması beklenir:

Terminal window
aggrega build --release release-negative-undeclared-key.yaml --auto-pull
# [… omitted: a refused: line carrying the message below]
# [DEVELOPER_ERROR E0156] .spec.components.web.uses.assistant.model
# invalid inject key: the from-key must name a provides key its source publishes
# (Aggregate adhoc-uses-socket-undeclared-key,
# at .spec.components.web.uses.assistant.model, "env", "ASSISTANT_API_KEY", "api_key",
# "core/ai-model/anthropic", "endpoint", "model")

Durma dersin kendisidir ve nerede tetiklendiği fark edilmeye değer kısımdır: sorunlu yol geçici soketi, uses.assistant’ı adlandırır ve içindeki iletim girdisinde değil, bağlantıda durur. from: anahtarı her kenarda hedef Component’in bildirilmiş provides değerlerine karşı denetlenir ve soketin geçici olması bu denetimde hiçbir şeyi değiştirmez. Bir soket adı icat edebilen bir yazar, yine de başkasının bileşeni üzerinde bir çıktı anahtarı icat edemez.

Önce ret gelir, ardından Aggregate ve kenarın yazıldığı yol, mekanizma ve girdinin altına yazıldığı iletim anahtarı, hatalı anahtar, karşısında çözümlendiği bileşen türü ve o türün bildirilmiş anahtarları sıralı olarak gelir; böylece düzeltme yalnızca iletiden görülebilir. Hiç provides bildirmeyen bir hedef Component de kendisine yapılan her from: başvurusunu aynı şekilde reddeder; yalnızca listelenecek bildirilmiş anahtar yoktur, bu yüzden ileti bileşen türünden sonra biter.

Hangisini yazmalı

Soketi katalogda bildirmek daha iyi yol olmaya devam eder ve standart kütüphane kataloğu da bunu yapar. Bildirilmiş bir soket, kenarın hangi bileşenlere ulaşabileceğini kısıtlayan bir selector, bir inject: izin listesi, kendi varsayılanlarına sahip kenar başına bir sözleşme ve bir açıklama taşır: öngörülmüş bir bağlantının, onu kuran varlıkla birlikte sürümlenen, incelenebilir bir ifadesi. Geçici bir soket bunların hiçbirini taşımaz ve kenar ancak onu yazan yazar kadar güvenlidir.

Geçici biçim bir kaçış yoludur; bu örneğin gösterdiği durum içindir: katalog yazarının öngörmediği, tek bir dağıtımın ihtiyaç duyduğu ve bir katalog değişikliğini beklemenin yayını beklemek anlamına geleceği bir bağlantı. Bedelini bilerek ona başvurun.

İki bedeli açıkça belirtmekte yarar var:

  • Yanlış yazılmış bir soket adı geçerli bir geçici sokettir, hata değildir. databases kastedilirken databses yazmak, amaçlanan soket üzerinden hiçbir şeyin akmadığı başarılı bir derleme üretir. Derleyici, bildirilmiş bir sokete bir düzenleme uzaklığındaki bir soket adını iki yazımı da belirten bir uyarı olarak bildirir (bkz. errors/warnings.md “Uses-socket near-miss lint”), ancak bu bir uyarıdır ve derlemenin sonucunu asla değiştirmez.
  • İki yüzey bilerek bu şekilde açık bırakılmamıştır. Bir Feature ekinin uses alanı yalnızca eklenen Feature’ın bildirdiği bir soketi adlandırabilir ve bir Release’in kenar başına uses alanı yalnızca tüketen Component’in bildirdiği bir soketi adlandırabilir. Bir operatör bir mimari içinde yapılandırır ve bağlar; onu yazmaz. Bu nedenle release-delivers.yaml, infra: taşır ve soketlerle ilgili hiçbir şey taşımaz: assistant soketi Aggregate yazarına aittir, yalnızca ona.

Sözleşmenin tamamı için bkz. entities/component.md “Topology Sockets: usesSchema” ve architecture/07-dependency-resolution.md.