Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

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:

InstanzTypwas es ist
dbcore/datastore/mariadbdie Datenbank
modelcore/ai-model/anthropicein Modell-Endpunkt; eine Realisierung in Referenzform, daher läuft für ihn keine Rechenressource
webcore/devtool/adminerdie 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: model

assistant 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:

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

Danach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:

Terminal window
cd adhoc-uses-socket

Build

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

Die 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: db kam über databases, den deklarierten Socket. Ihr Wert ist das provides.host des Datenbank-Recipe — ein Compose-Dienstname.
  • ASSISTANT_ENDPOINT und ASSISTANT_MODEL kamen über assistant, den Ad-hoc-Socket, und tragen das provides.endpoint und das provides.model des 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_key

core/ai-model/anthropic deklariert endpoint und model in seiner Säule provides und sonst nichts. Der Build soll fehlschlagen:

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

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 databses schreibt, wo databases gemeint 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 uses einer Feature-Anbindung darf nur einen Socket benennen, den das angebundene Feature deklariert, und das kantenbezogene uses eines 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.yaml trägt daher infra: und nichts über Sockets — der Socket assistant gehö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.