Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

Socket yang tidak dideklarasikan siapa pun, mengirimkan nilai nyata

Contoh ini mengajarkan satu baris, beserta kedua bagiannya:

Konsumen boleh menciptakan koneksinya. Konsumen hanya boleh mengonsumsi apa yang dideklarasikan oleh produsen.

Seorang penulis Aggregate menulis entri uses: pada komponennya sendiri di bawah nama socket yang tidak dideklarasikan oleh entitas katalog mana pun. Edge tersebut dibangun dan mengirimkan nilai — nilainya sampai ke artefak hasil render persis seperti melalui socket yang dideklarasikan. Namun kunci yang boleh dibawa edge tersebut tetap dideklarasikan oleh target: sebutkan satu kunci yang tidak dideklarasikan target, dan build akan berhenti.

Semua yang ada di sini di-resolve dari katalog pustaka standar. Workspace ini tidak menulis Component, Feature, atau Recipe sendiri.

Stack

Tiga komponen, dan salah satunya dihubungkan dengan dua cara berbeda:

instanstipeapa itu
dbcore/datastore/mariadbbasis data
modelcore/ai-model/anthropicendpoint model; realisasi berbentuk referensi, sehingga tidak ada komputasi yang berjalan untuknya
webcore/devtool/adminerkonsol, yang mengonsumsi keduanya

core/devtool/adminer mendeklarasikan tepat satu socket:

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

Itulah seluruh hal yang diantisipasi penulisnya. Konsol yang berada di depan basis data adalah koneksi yang mereka bayangkan; konsol yang membawa endpoint model di environment-nya tidak.

Apa yang ditulis Aggregate

aggregate-delivers.yaml menghubungkan kedua edge dari satu blok uses::

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 tidak muncul di usesSchema mana pun, baik pada Component ini maupun yang lain. Meski demikian, ini sah: diamnya katalog tentang suatu socket berarti koneksi tersebut tidak diantisipasi, bukan berarti dilarang, dan pengembang memiliki topologi aplikasinya sendiri.

Yang dilepaskan oleh socket ad-hoc adalah persis apa yang akan dibawa oleh entri usesSchema yang tidak ada — tidak ada selector, sehingga tidak ada yang membatasi komponen mana yang boleh dicapai edge dan pemeriksaan keamanan tipe lintas node tidak memiliki apa pun untuk dievaluasi; tidak ada allowlist inject:; tidak ada valueSchema atau infraSchema per edge, sehingga values: dan infra: per edge tidak memiliki kontrak untuk diperiksa dan tidak ada nilai default yang dideklarasikan untuk diwarisi. Konfigurasi per edge yang ditulis pada socket seperti itu diterima dan diteruskan tanpa diperiksa, sebagaimana perilaku setiap socket tanpa kontrak untuk pilar tersebut — socket yang dideklarasikan tetapi tidak menulis valueSchema berada pada posisi yang sama.

Yang tidak dilepaskannya adalah apa yang boleh dibawa edge. endpoint dan model keduanya adalah kunci yang dideklarasikan core/ai-model/anthropic dalam pilar provides-nya.

Membuat contoh

Anda dapat mem-build contoh ini dengan perintah di bawah, atau meminta asisten AI Anda mem-build-nya untuk Anda.

Tulis contoh ke folder baru yang dinamai sesuai contoh itu:

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

Kemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:

Terminal window
cd adhoc-uses-socket

Build

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

Output hasil render dan lockfile dihasilkan, bukan dikirimkan: contoh ini meng-commit input-nya dan membuat ulang semua yang lain. --auto-pull me-resolve lockfile selama build; menjalankan aggrega pull --release release-delivers.yaml sekali sebelumnya melakukan hal yang sama dan memungkinkan build berikutnya berjalan tanpa flag sama sekali. Entitas katalog di-resolve dari hub.aggrega.ai, registry default yang disebut .aggrega-config.yaml, sehingga baik build maupun aggrega inspect tidak memerlukan flag --catalog.

Dengan asisten AI

Asisten AI yang disiapkan dengan tool Aggrega dapat melakukan hal yang sama: tempelkan prompt ini ke asisten tersebut.

Gunakan hanya tool Aggrega, dan jangan membuat folder apa pun sendiri. Jika folder workspace belum berisi folder `adhoc-uses-socket`, panggil tool `scaffold` sekali dengan `example` diatur ke `adhoc-uses-socket` dan tanpa `dir`: tool itu menulis contoh ke folder baru `adhoc-uses-socket`. Lalu panggil tool `build` dengan `workspace_root` diatur ke `adhoc-uses-socket`, `release` diatur ke `release-delivers.yaml`, `auto_pull` diatur ke true, dan `write` diatur ke true. Beri tahu saya file mana saja yang ditulis build; file-file itu berada di bawah `adhoc-uses-socket/dist/`.

Membaca output

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

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]

Empat variabel, tiga di antaranya dikirimkan melalui edge, dan output tidak mencatat socket mana yang dideklarasikan:

  • ADMINER_DEFAULT_SERVER: db tiba melalui databases, socket yang dideklarasikan. Nilainya adalah provides.host milik Recipe basis data — nama layanan Compose.
  • ASSISTANT_ENDPOINT dan ASSISTANT_MODEL tiba melalui assistant, socket ad-hoc, membawa provides.endpoint dan provides.model milik Recipe model.

Semuanya berada dalam satu map, dalam urutan penulis, tanpa penanda, tanpa anotasi, dan tanpa perbedaan urutan di antara mereka. Itulah intinya: socket ad-hoc adalah hal yang berbeda untuk dideklarasikan, bukan hal yang berbeda untuk dikirimkan. Hanya ada satu jalur pengiriman dan kedua edge menempuhnya.

ASSISTANT_ENDPOINT juga layak dibaca sebagai fakta kompilasi ahead-of-time. Compiler tidak menghubungi Anthropic untuk menemukan https://api.anthropic.com; Recipe memancarkannya sebagai string penunjuk deterministik yang bersumber dari infra.endpoint milik komponen model, dan compiler merutekan string itu tanpa menafsirkannya. Adminer sendiri tidak membaca variabel ASSISTANT_* mana pun — pengembanglah yang memilih kunci pengiriman tersebut, dan container konsol membawanya untuk apa pun yang membacanya di sana.

Graf yang dipancarkan build mencatat perbedaan ini meskipun artefak hasil render tidak: setiap edge membawa field socket_declaration yang bernilai declared atau ad-hoc, sehingga organisasi yang ingin setiap koneksi melalui socket yang dideklarasikan oleh Architect-nya menyatakan hal itu sebagai kebijakan tata kelola alih-alih mengandalkan compiler untuk memiliki opini. Lihat architecture/11-governance-and-compliance.md.

Kontrol: apa yang tetap tidak boleh diciptakan konsumen

aggregate-undeclared-key.yaml adalah aggregate-delivers.yaml dengan satu perubahan. Edge ad-hoc meminta kunci ketiga:

- in: ASSISTANT_API_KEY
from: api_key

core/ai-model/anthropic mendeklarasikan endpoint dan model dalam pilar provides-nya, dan tidak ada yang lain. Build ini diharapkan gagal:

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")

Penghentian inilah pelajarannya, dan di mana ia terjadi adalah bagian yang patut diperhatikan: path yang bermasalah menyebut socket ad-hoc, uses.assistant, dan berhenti pada koneksi, bukan pada entri pengiriman di dalamnya. Kunci from: diperiksa terhadap provides yang dideklarasikan Component target pada setiap edge, dan sifat ad-hoc socket tidak mengubah apa pun pada pemeriksaan itu. Penulis yang boleh menciptakan nama socket tetap tidak boleh menciptakan kunci output pada komponen milik orang lain.

Penolakan disebutkan lebih dulu, lalu Aggregate dan path tempat edge ditulis, mekanisme dan kunci pengiriman tempat entri ditulis, kunci yang bermasalah, tipe komponen yang digunakan untuk me-resolve-nya, dan kunci yang dideklarasikan tipe itu dalam urutan terurut — sehingga perbaikannya terlihat dari pesan itu saja. Component target yang sama sekali tidak mendeklarasikan provides juga menolak setiap referensi from: ke komponen tersebut; hanya saja tidak ada kunci yang dideklarasikan untuk dicantumkan, sehingga pesan berakhir setelah tipe komponen.

Mana yang sebaiknya ditulis

Mendeklarasikan socket di katalog tetap merupakan jalur yang lebih baik, dan itulah yang dilakukan katalog pustaka standar. Socket yang dideklarasikan membawa selector yang membatasi komponen mana yang boleh dicapai edge, allowlist inject:, kontrak per edge dengan nilai default-nya sendiri, dan deskripsi — pernyataan yang dapat ditinjau tentang koneksi yang diantisipasi, diberi versi bersama entitas yang membuatnya. Socket ad-hoc tidak membawa satu pun dari itu, dan edge hanya seaman penulis yang menulisnya.

Bentuk ad-hoc adalah jalan keluar, untuk kasus yang ditunjukkan contoh ini: koneksi yang tidak diantisipasi penulis katalog, dibutuhkan oleh satu deployment, ketika menunggu perubahan katalog berarti menunda pengiriman. Gunakan bentuk ini dengan mengetahui biayanya.

Dua biaya patut dinyatakan secara gamblang:

  • Nama socket yang salah eja adalah socket ad-hoc yang sah, bukan kesalahan. Menulis databses padahal yang dimaksud databases menghasilkan build hijau tanpa ada yang mengalir melalui socket yang dimaksud. Compiler melaporkan nama socket yang berjarak satu suntingan dari nama yang dideklarasikan sebagai peringatan advisori yang menyebut kedua ejaan — lihat errors/warnings.md “Uses-socket near-miss lint” — tetapi itu hanya peringatan dan tidak pernah mengubah hasil build.
  • Dua permukaan sengaja tidak dibuka dengan cara ini. uses pada lampiran Feature hanya boleh menyebut socket yang dideklarasikan Feature yang dilampirkan, dan uses per edge pada Release hanya boleh menyebut socket yang dideklarasikan Component konsumen. Operator mengonfigurasi dan menghubungkan di dalam sebuah arsitektur; mereka tidak menulisnya. Karena itu release-delivers.yaml membawa infra: dan tidak ada apa pun tentang socket — socket assistant adalah milik penulis Aggregate, dan hanya milik mereka.

Untuk kontrak lengkapnya, lihat entities/component.md “Topology Sockets: usesSchema” dan architecture/07-dependency-resolution.md.