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

Ein veröffentlichter Wrapper, bedient vom Recipe seiner Basis

Dieses Beispiel lehrt eine Sache: Eine Component, die eine andere per extends erweitert, erbt den gesamten Datenvertrag dieser Basis, sodass jedes für die Basis geschriebene Recipe die erweiternde Component bereits implementiert. Eine spezialisierte Variante einer Komponente der Standardbibliothek zu veröffentlichen, kostet daher eine Katalogentität und eine Manifest-Zeile — kein eigenes Recipe und keine Änderung an der Basis.

Der Wrapper hier ist example/gateway/nginx-reviewed. Er wird im Katalog neben core/gateway/nginx ausgeliefert, der Komponente, die er erweitert.

Was der Wrapper hinzufügt und was er erbt

Die gesamte verfasste Oberfläche des Wrappers besteht aus Metadaten plus einem Socket:

metadata:
name: example/gateway/nginx-reviewed
labels:
component.aggrega.ai/type: server
component.aggrega.ai/category: gateway
gateway.example.com/audit-tier: reviewed # added
gateway.example.com/data-zone: eu-west # added
annotations:
governance.example.com/review-board: platform-architecture # added
governance.example.com/contact: platform-architecture@example.com
spec:
extends: core/gateway/nginx:1.0.0
schema: inherited
usesSchema:
reviewed_upstream: # added
selector: "gateway.example.com/audit-tier=reviewed"
inject: [env]

schema: inherited ist die literale Markierung, die eine erweiternde Component anstelle eines Blocks schema: schreibt. Sie besagt, dass die drei Datensäulen — values, infra und provides — die der Basis sind, genau so, wie die Basis sie verfasst hat. Der Wrapper deklariert keinen eigenen Säulenschlüssel und kann es auch nicht: Der Vertrag gehört der Basis, in jeder Tiefe einer Kette.

Alles, was der Wrapper nicht erwähnt, erbt er. aggrega inspect example/gateway/nginx-reviewed --resolved zeigt die zusammengeführte Entität, und zwei Dinge darin lohnen eine genaue Lektüre:

  • Drei Sockets uses, nicht einer: upstream und guard (die der Basis, wobei upstream component.aggrega.ai/type=server auswählt) und reviewed_upstream (der des Wrappers). Erweitern ergänzt einen Socket; es ersetzt die Menge nicht.
  • Die drei Säulen der Basis, wörtlich — values.upstream_path, infra.port / engine_version / compute / overrides und provides.host / port / protocol, jeweils mit den eigenen Beschreibungen der Basis.

Was ein konsumierendes Aggregate schreibt

aggregate-reviewed.yaml deklariert zwei Gateway-Schichten als den Wrapper, vor einer Datenbankkonsole:

components:
edge:
type: example/gateway/nginx-reviewed
values:
upstream_path: /api/ # declared by the base; the wrapper never mentions it
uses:
reviewed_upstream: # the socket the wrapper ADDS
internal: { target: internal, inject: { env: [ ... ] } }
internal:
type: example/gateway/nginx-reviewed
values:
upstream_path: /
uses:
upstream: # the socket the wrapper INHERITS
console: { target: console, inject: { env: [ ... ] } }
console:
type: core/devtool/adminer

upstream_path ist der Schlüssel, auf den es ankommt. Er ist in der Säule values von core/gateway/nginx deklariert und kommt in der Datei des Wrappers nirgends vor, und doch schreibt ein Autor ihn auf eine Instanz des Wrappers, und er erreicht die gerenderte Gateway-Konfiguration. Das bedeutet es in der Praxis, die Säulen vollständig zu erben.

Das Manifest ist die andere Hälfte, und es ist eine Zeile pro Typ:

mappings:
components:
type:
example/gateway/nginx-reviewed:1.0.0: compose/nginx:1.0.0
core/gateway/nginx:1.0.0: compose/nginx:1.0.0
core/devtool/adminer:1.0.0: compose/adminer:1.0.0

Beide Gateway-Zeilen nennen dasselbe Recipe. compose/nginx deklariert implements: core/gateway/nginx:1.0.0, und ein Recipe, das eine Basis nennt, ist die Implementierung für jede Component, die diese Basis erweitert — daher wird der Wrapper unverändert davon bedient. Hier gelten zwei Tatsachen zugleich, und sie sind voneinander getrennt:

  • Das Recipe passt. Es gibt kein Recipe, das den eigenen Typ des Wrappers implementiert, und es wird keines gebraucht.
  • Die Zuordnung ist trotzdem erforderlich. Die Recipe-Auswahl erfolgt über den exakten Zuordnungsschlüssel, daher braucht der Wrapper einen eigenen Eintrag type; er erbt den der Basis nicht. Eine Wrapper-Instanz ohne eigenen Eintrag bricht mit der Diagnose für nicht zugeordnete Instanzen ab, auch wenn ihre Basis zugeordnet ist.

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 extends-wrapper

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

Terminal window
cd extends-wrapper

Build

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

Die gerenderte Ausgabe und das Lockfile werden generiert, nicht mitgeliefert: Dieses Beispiel committet seine Eingaben und regeneriert alles andere. --auto-pull löst das Lockfile während des Builds auf; aggrega pull --release release-reviewed.yaml, einmal vorab ausgeführt, tut dasselbe und lässt spätere Builds ganz ohne Flag laufen.

Sowohl der Wrapper als auch die Basis, die er erweitert, liegen im gemeinsamen Katalog, der aus hub.aggrega.ai aufgelöst wird, der Standard-Registry, die .aggrega-config.yaml deklariert. Der Build-Befehl braucht kein Flag --catalog, und aggrega inspect, aus diesem Verzeichnis ausgeführt, ebenso wenig.

Der Pull ruft core/gateway/nginx ab, weil der Wrapper sie erweitert: Eine Basis ist eine Abhängigkeit von allem, was sie erweitert, daher folgt der Pull dem extends: des Wrappers und pinnt die Basis im Lockfile, ob das Manifest sie nennt oder nicht. Das Manifest bildet die Basis hier aus einem anderen Grund ab — die Kontrollbereitstellung weiter unten deklariert eine Instanz der Basis selbst.

Die gerenderte dist/compose/docker-compose.yaml enthält den Beleg:

edge:
image: nginx:1.27.5-alpine
entrypoint:
- /bin/sh
- -c
- echo 'server { listen 8080; location /api/ { proxy_pass http://internal:8081; } }' > /etc/nginx/conf.d/default.conf && exec nginx -g 'daemon off;'
[… omitted: the published port]
labels:
[… omitted: the other provenance labels every rendered document carries]
aggrega.ai/recipe-uri: nginx:1.0.0
[… omitted: the service's network, its depends_on naming internal, and its healthcheck]

Drei Lesarten, geordnet nach dem, was sie belegen:

  • aggrega.ai/recipe-uri: nginx:1.0.0 — das Recipe der Basis hat diesen Service geformt. Das Herkunftslabel an einer Wrapper-Instanz nennt das Recipe der Basis, weil dies das Recipe ist, das sie gerendert hat.
  • location /api/ — values.upstream_path, ein Schlüssel, den nur die Basis deklariert, auf einer Wrapper-Instanz verfasst und gerendert.
  • proxy_pass http://internal:8081 — die aufgelöste Kante reviewed_upstream. provides.host und provides.port des Ziels kamen im Injektionskontext unter den Zustellschlüsseln an, die das Recipe der Basis liest, sodass ein Socket, den der Wrapper hinzugefügt hat, durch ein Recipe fließt, das nie davon gehört hat.

Das Lockfile, das der Build auflöst, hält dieselbe Tatsache aus Sicht des Resolvers fest: ein einziger Eintrag compose/nginx:1.0.0 mit einem Digest, referenziert von beiden Zuordnungsschlüsseln — dem Typ der Basis und dem des Wrappers.

Die Labels und Annotationen des Wrappers reisen mit der aufgelösten Kante: Der Render-Kontext eines konsumierenden Knotens trägt die provides, labels und Annotationen jedes Ziels, sodass der Kontext von edge weiß, dass sein Upstream audit-tier=reviewed ist und wer ihn geprüft hat. Ob irgendetwas davon in einem gerenderten Artefakt erscheint, entscheidet das Recipe — diese Labels und Annotationen sind Komponentenidentität, die Selektoren und Policies lesen, keine Ausgabe, die der Compiler aufprägt.

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 ausschließlich die Aggrega-Tools und legen Sie selbst keinen Ordner an. Wenn der Arbeitsbereichsordner noch keinen Ordner `extends-wrapper` enthält, rufen Sie das Tool `scaffold` einmal mit `example` auf `extends-wrapper` gesetzt und ohne `dir` auf: Es schreibt das Beispiel in einen neuen Ordner `extends-wrapper`. Rufen Sie dann das Tool `build` mit `workspace_root` auf `extends-wrapper`, `release` auf `release-reviewed.yaml`, `auto_pull` auf true und `write` auf true gesetzt auf. Nennen Sie mir die Dateien, die der Build geschrieben hat; sie liegen unter `extends-wrapper/dist/`.

Die Kontrolle: wozu das hinzugefügte Label dient

aggregate-unreviewed.yaml ist aggregate-reviewed.yaml mit einer Änderung — die interne Schicht ist als die bloße Basis core/gateway/nginx statt als der Wrapper deklariert — und es soll fehlschlagen:

Terminal window
aggrega build --release release-negative-unreviewed.yaml --auto-pull
# [DEVELOPER_ERROR E0007] aggregate-unreviewed.yaml at .spec.components.edge.uses.reviewed_upstream.internal
# selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.

Der Abbruch ist die Lektion. Die Basis erfüllt ihren eigenen Socket upstream — sie ist component.aggrega.ai/type=server, und die interne Schicht ist auf genau dieselbe Weise über diesen Socket verdrahtet —, aber sie trägt kein Label audit-tier, daher weist der strengere Socket des Wrappers sie zurück. Das Label, das der Wrapper hinzufügt, macht eine Instanz davon auswählbar, und am Selektor zeigt sich das.

Zwei weitere Abbrüche sind wissenswert, und beide sind das Schema, das seine Arbeit tut:

  • Eine Component, die extends deklariert und unter schema: Säuleninhalte verfasst, wird beim Laden des Dokuments zurückgewiesen, unter Nennung der Einschränkung. Ebenso eine, die schema: ganz weglässt. schema: inherited ist die einzige akzeptierte Form, und sie wird geschrieben statt impliziert, sodass ein Leser einen geerbten Säulenblock nie mit einem vergessenen verwechseln kann.
  • Ein Schlüssel values, den die Basis nicht deklariert, wird an einer Wrapper-Instanz zurückgewiesen, am verfassten Pfad, weil der durchgesetzte Vertrag der der Basis ist.

Warum das nützlich ist

Eine Organisation, die sich auf eine geprüfte Form für eine Komponente der Standardbibliothek festgelegt hat, braucht einen Ort, an dem sie sie aufbewahrt. In Prosa festgehalten, werden die Labels, Annotationen und Sockets in jedem Aggregate wiederholt, das sie braucht, und laufen dabei auseinander. Als Component veröffentlicht, die die Basis erweitert, wird die Form zu einer versionierten, prüfbaren Katalogentität mit einem Namen: Ein Team, das sie konsumiert, schreibt type: example/gateway/nginx-reviewed und eine Manifest-Zeile und erbt den gesamten Vertrag der Basis samt jedem bereits dafür geschriebenen Recipe, auf jedem Ziel, das die Basis unterstützt.

Die Kosten des Wrappers sind es, die das funktionieren lassen: Er fügt Struktur und Metadaten hinzu und sonst nichts. Weil er keine Säulen deklariert, werden eine Instanz des Wrappers und eine Instanz der Basis gegen einen einzigen Vertrag validiert, und ein für die Basis geschriebenes Recipe kann von einer Spezialisierung davon nie überrascht werden.