Ein Socket, den niemand deklariert hat, liefert echte Werte
Dieses Beispiel lehrt eine Grenzlinie, und zwar beide ihrer Hälften:
Ein Konsument darf die Verbindung erfinden. Er darf nur konsumieren, was der Produzent deklariert.
Der Autor eines Aggregate schreibt einen Eintrag uses: an seiner eigenen Komponente unter einem Socket-Namen, den keine Katalogentität deklariert. Die Kante wird gebaut und liefert — der Wert erreicht das gerenderte Artefakt genau so, wie er es über einen deklarierten Socket täte. Doch welche Schlüssel diese Kante tragen darf, hat weiterhin das Ziel zu deklarieren: Nennen Sie einen, den das Ziel nicht deklariert, und der Build bricht ab.
Alles hier wird aus dem Katalog der Standardbibliothek aufgelöst. Der Workspace schreibt keine eigene Component, kein eigenes Feature und kein eigenes Recipe.
Der Stack
Drei Komponenten, und eine davon ist auf zwei verschiedene Arten verdrahtet:
| Instanz | Typ | was es ist |
|---|---|---|
db | core/datastore/mariadb | die Datenbank |
model | core/ai-model/anthropic | ein Modell-Endpunkt; eine Realisierung in Referenzform, daher läuft für ihn keine Rechenressource |
web | core/devtool/adminer | die Konsole, die beide konsumiert |
core/devtool/adminer deklariert genau einen Socket:
usesSchema: databases: selector: "component.aggrega.ai/type=stateful-server" inject: [env]Das ist alles, was sein Autor vorhergesehen hat. Eine Konsole vor einer Datenbank ist die Verbindung, die er im Sinn hatte; eine Konsole, die einen Modell-Endpunkt in ihrer Umgebung trägt, ist es nicht.
Was das Aggregate schreibt
aggregate-delivers.yaml verdrahtet beide Kanten aus einem einzigen Block 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 erscheint in keinem usesSchema, weder an dieser Component noch an einer anderen. Es ist trotzdem zulässig: Schweigt der Katalog zu einem Socket, bedeutet das, dass die Verbindung nicht vorhergesehen wurde, nicht dass sie verboten ist, und der Entwickler ist Eigentümer der Topologie seiner eigenen Anwendung.
Was der Ad-hoc-Socket aufgibt, ist genau das, was der fehlende Eintrag in usesSchema getragen hätte — kein selector, sodass nichts einschränkt, welche Komponente die Kante erreichen darf, und die knotenübergreifende Typsicherheitsprüfung nichts auszuwerten hat; keine Allowlist inject:; kein kantenbezogenes valueSchema oder infraSchema, sodass kantenbezogene values: und infra: keinen Vertrag haben, gegen den sie geprüft werden, und keine deklarierten Standardwerte, die sie erben könnten. Kantenbezogene Konfiguration, die an einem solchen Socket geschrieben wird, wird akzeptiert und reist ungeprüft mit, und so verhält sich jeder Socket ohne Vertrag für diese Säule — ein deklarierter Socket, der kein valueSchema schreibt, ist in derselben Lage.
Was er nicht aufgibt, ist das, was die Kante tragen darf. endpoint und model sind beides Schlüssel, die core/ai-model/anthropic in seiner Säule provides deklariert.
Das Beispiel generieren
Sie können dieses Beispiel mit den folgenden Befehlen bauen oder es von Ihrem KI-Assistenten für Sie bauen lassen.
Schreiben Sie das Beispiel in einen neuen Ordner, der nach ihm benannt ist:
aggrega scaffold --example adhoc-uses-socketDanach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:
cd adhoc-uses-socketBuild
aggrega build --release release-delivers.yaml --auto-pullDie gerenderte Ausgabe und das Lockfile werden erzeugt, nicht mitgeliefert: Dieses Beispiel committet seine Eingaben und erzeugt alles andere neu. --auto-pull löst das Lockfile während des Builds auf; einmal vorher aggrega pull --release release-delivers.yaml auszuführen, bewirkt dasselbe und lässt spätere Builds ganz ohne Flag laufen. Die Katalogentitäten werden aus hub.aggrega.ai aufgelöst, der Standard-Registry, die .aggrega-config.yaml nennt, sodass weder der Build noch aggrega inspect ein Flag --catalog braucht.
Mit einem KI-Assistenten
Ein KI-Assistent, der mit den Tools von Aggrega eingerichtet ist, kann dasselbe tun: Fügen Sie ihm diesen Prompt ein.
Verwenden Sie nur die Aggrega-Tools und legen Sie selbst keinen Ordner an. Wenn der Workspace-Ordner noch keinen Ordner `adhoc-uses-socket` enthält, rufen Sie das Tool `scaffold` einmal auf, mit `example` auf `adhoc-uses-socket` gesetzt und ohne `dir`: Es schreibt das Beispiel in einen neuen Ordner `adhoc-uses-socket`. Rufen Sie dann das Tool `build` auf, mit `workspace_root` auf `adhoc-uses-socket`, `release` auf `release-delivers.yaml`, `auto_pull` auf true und `write` auf true gesetzt. Nennen Sie mir die Dateien, die der Build geschrieben hat; sie liegen unter `adhoc-uses-socket/dist/`.Die Ausgabe lesen
dist/compose/docker-compose.yaml, der Dienst 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]Vier Variablen, drei davon über Kanten geliefert, und die Ausgabe hält nicht fest, welcher Socket deklariert war:
ADMINER_DEFAULT_SERVER: dbkam überdatabases, den deklarierten Socket. Ihr Wert ist dasprovides.hostdes Datenbank-Recipe — ein Compose-Dienstname.ASSISTANT_ENDPOINTundASSISTANT_MODELkamen überassistant, den Ad-hoc-Socket, und tragen dasprovides.endpointund dasprovides.modeldes Modell-Recipe.
Sie stehen in einer einzigen Map, in Autorenreihenfolge, ohne Markierung, ohne Annotation und ohne Unterschied in der Reihenfolge zwischen ihnen. Genau darum geht es: Ein Ad-hoc-Socket ist etwas anderes beim Deklarieren, nicht etwas anderes beim Liefern. Es gibt einen einzigen Lieferweg, und beide Kanten nehmen ihn.
ASSISTANT_ENDPOINT lohnt sich auch als Tatsache der Ahead-of-Time-Kompilierung zu lesen. Der Compiler hat Anthropic nicht kontaktiert, um https://api.anthropic.com zu ermitteln; das Recipe hat es als deterministische Zeiger-Zeichenkette ausgegeben, die aus dem infra.endpoint der Modellkomponente stammt, und der Compiler hat diese Zeichenkette weitergeleitet, ohne sie zu interpretieren. Adminer selbst liest keine der beiden Variablen ASSISTANT_* — der Entwickler hat diese Lieferschlüssel gewählt, und der Container der Konsole trägt sie für das, was sie dort liest.
Der Graph, den der Build ausgibt, hält die Unterscheidung fest, auch wenn das gerenderte Artefakt es nicht tut: Jede Kante trägt ein Feld socket_declaration mit dem Wert declared oder ad-hoc, sodass eine Organisation, die möchte, dass jede Verbindung über einen von ihren Architekten deklarierten Socket läuft, dies als Governance-Richtlinie ausdrückt, statt darauf zu setzen, dass der Compiler eine Meinung vertritt. Siehe architecture/11-governance-and-compliance.md.
Die Kontrolle: Was der Konsument trotzdem nicht erfinden darf
aggregate-undeclared-key.yaml ist aggregate-delivers.yaml mit einer einzigen Änderung. Die Ad-hoc-Kante verlangt einen dritten Schlüssel:
- in: ASSISTANT_API_KEY from: api_keycore/ai-model/anthropic deklariert endpoint und model in seiner Säule provides und sonst nichts. Der Build soll fehlschlagen:
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")Der Abbruch ist die Lektion, und wo er auslöst, ist der Teil, auf den es zu achten lohnt: Der fehlerhafte Pfad nennt den Ad-hoc-Socket, uses.assistant, und endet bei der Verbindung statt beim Lieferungseintrag darin. Der Schlüssel from: wird auf jeder Kante gegen die deklarierten provides der Ziel-Component geprüft, und dass der Socket ad hoc ist, ändert an dieser Prüfung nichts. Ein Autor, der einen Socket-Namen erfinden darf, darf trotzdem keinen Ausgabeschlüssel an der Komponente eines anderen erfinden.
Zuerst kommt die Zurückweisung, dann das Aggregate und der Pfad, an dem die Kante geschrieben wurde, der Mechanismus und der Lieferschlüssel, unter dem der Eintrag geschrieben wurde, der fehlerhafte Schlüssel, der Komponententyp, gegen den er aufgelöst wurde, und die deklarierten Schlüssel dieses Typs in sortierter Reihenfolge — sodass die Korrektur allein aus der Meldung ersichtlich ist. Eine Ziel-Component, die überhaupt kein provides deklariert, weist jede Referenz from: auf sie ebenso zurück; es gibt dann einfach keine deklarierten Schlüssel aufzulisten, sodass die Meldung nach dem Komponententyp endet.
Welche Form man schreibt
Den Socket im Katalog zu deklarieren bleibt der bessere Weg, und es ist das, was der Katalog der Standardbibliothek tut. Ein deklarierter Socket trägt einen selector, der einschränkt, welche Komponenten die Kante erreichen darf, eine Allowlist inject:, einen kantenbezogenen Vertrag mit eigenen Standardwerten und eine Beschreibung — eine überprüfbare Aussage über eine vorhergesehene Verbindung, versioniert mit der Entität, die sie trifft. Ein Ad-hoc-Socket trägt nichts davon, und die Kante ist nur so sicher wie der Autor, der sie geschrieben hat.
Die Ad-hoc-Form ist ein Ausweg, für den Fall, den dieses Beispiel zeigt: eine Verbindung, die der Katalogautor nicht vorhergesehen hat, die ein einzelnes Release braucht und bei der das Warten auf eine Katalogänderung bedeuten würde, mit dem Ausliefern zu warten. Greifen Sie darauf zurück und wissen Sie dabei, was es kostet.
Zwei Kosten sollte man klar benennen:
- Ein falsch geschriebener Socket-Name ist ein zulässiger Ad-hoc-Socket, kein Fehler. Wer
databsesschreibt, wodatabasesgemeint war, erhält einen grünen Build, in dem nichts über den beabsichtigten Socket fließt. Der Compiler meldet einen Socket-Namen, der eine Bearbeitung von einem deklarierten entfernt ist, als Hinweis, der beide Schreibweisen nennt — siehe errors/warnings.md „Uses-socket near-miss lint (Lint für beinahe passende uses-Sockets)“ —, aber es ist eine Warnung und ändert nie das Urteil des Builds. - Zwei Oberflächen sind bewusst nicht auf diese Weise offen. Das
useseiner Feature-Anbindung darf nur einen Socket benennen, den das angebundene Feature deklariert, und das kantenbezogeneuseseines Release darf nur einen Socket benennen, den die konsumierende Component deklariert. Ein Operator konfiguriert und verdrahtet innerhalb einer Architektur; er verfasst sie nicht.release-delivers.yamlträgt daherinfra:und nichts über Sockets — der Socketassistantgehört dem Autor des Aggregate, und nur ihm.
Den vollständigen Vertrag finden Sie in entities/component.md „Topology Sockets: usesSchema (Topologie-Sockets)“ und architecture/07-dependency-resolution.md.