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:
| instans | tipe | apa itu |
|---|---|---|
db | core/datastore/mariadb | basis data |
model | core/ai-model/anthropic | endpoint model; realisasi berbentuk referensi, sehingga tidak ada komputasi yang berjalan untuknya |
web | core/devtool/adminer | konsol, 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: modelassistant 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:
aggrega scaffold --example adhoc-uses-socketKemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:
cd adhoc-uses-socketBuild
aggrega build --release release-delivers.yaml --auto-pullOutput 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: dbtiba melaluidatabases, socket yang dideklarasikan. Nilainya adalahprovides.hostmilik Recipe basis data — nama layanan Compose.ASSISTANT_ENDPOINTdanASSISTANT_MODELtiba melaluiassistant, socket ad-hoc, membawaprovides.endpointdanprovides.modelmilik 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_keycore/ai-model/anthropic mendeklarasikan endpoint dan model dalam pilar provides-nya,
dan tidak ada yang lain. Build ini diharapkan gagal:
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
databsespadahal yang dimaksuddatabasesmenghasilkan 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.
usespada lampiran Feature hanya boleh menyebut socket yang dideklarasikan Feature yang dilampirkan, danusesper edge pada Release hanya boleh menyebut socket yang dideklarasikan Component konsumen. Operator mengonfigurasi dan menghubungkan di dalam sebuah arsitektur; mereka tidak menulisnya. Karena iturelease-delivers.yamlmembawainfra:dan tidak ada apa pun tentang socket — socketassistantadalah milik penulis Aggregate, dan hanya milik mereka.
Untuk kontrak lengkapnya, lihat
entities/component.md “Topology Sockets: usesSchema” dan
architecture/07-dependency-resolution.md.