Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Un wrapper pubblicato, servito dalla Recipe della sua base

Questo esempio insegna una cosa sola: un Component che extends un altro eredita l’intero contratto dei dati di quella base, quindi ogni Recipe scritta per la base implementa già il Component che la estende. Pubblicare una variante specializzata di un componente della libreria standard costa quindi un’entità di catalogo e una riga di Manifest — nessuna Recipe propria, e nessuna modifica alla base.

Il wrapper qui è example/gateway/nginx-reviewed. È incluso nel catalogo accanto a core/gateway/nginx, il componente che estende.

Che cosa aggiunge il wrapper, e che cosa eredita

L’intera superficie scritta dall’autore del wrapper è costituita da metadati più un 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 è il marcatore letterale che un Component che ne estende un altro scrive al posto di un blocco schema:. Dichiara che i tre pilastri dei dati — values, infra e provides — sono quelli della base, esattamente come la base li ha scritti. Il wrapper non dichiara alcuna chiave di pilastro propria e non può farlo: il contratto appartiene alla base, a ogni profondità di una catena.

Tutto ciò che il wrapper non menziona, lo eredita. aggrega inspect example/gateway/nginx-reviewed --resolved mostra l’entità unita, e due cose al suo interno meritano una lettura attenta:

  • Tre socket uses, non uno: upstream e guard (quelli della base, con upstream che seleziona component.aggrega.ai/type=server) e reviewed_upstream (quello del wrapper). Estendere aggiunge un socket; non sostituisce l’insieme.
  • I tre pilastri della base, alla lettera — values.upstream_path, infra.port / engine_version / compute / overrides, e provides.host / port / protocol, ciascuno con le descrizioni proprie della base.

Che cosa scrive un Aggregate consumatore

aggregate-reviewed.yaml dichiara due livelli di gateway come il wrapper, davanti a una console di database:

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 è la chiave da notare. È dichiarata nel pilastro values di core/gateway/nginx e non compare da nessuna parte nel file del wrapper, eppure un autore la scrive su un’istanza del wrapper e raggiunge la configurazione renderizzata del gateway. Ecco che cosa significa in pratica ereditare i pilastri per intero.

Il Manifest è l’altra metà, ed è una riga per tipo:

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

Entrambe le righe dei gateway nominano la stessa Recipe. compose/nginx dichiara implements: core/gateway/nginx:1.0.0, e una Recipe che nomina una base è l’implementazione per ogni Component che estende quella base — quindi il wrapper è servito da essa senza modifiche. Qui valgono due fatti contemporaneamente, e sono distinti:

  • La Recipe corrisponde. Non esiste alcuna Recipe che implementi il tipo proprio del wrapper, e non ne serve alcuna.
  • La mappatura è comunque richiesta. La selezione della Recipe avviene per chiave di mappatura esatta, quindi il wrapper ha bisogno di una propria voce type; non eredita quella della base. Un’istanza del wrapper senza una voce propria si arresta con la diagnostica di istanza non mappata anche quando la sua base è mappata.

Generare l’esempio

Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.

Scrivi l’esempio in una nuova cartella che porta il suo nome:

Terminal window
aggrega scaffold --example extends-wrapper

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:

Terminal window
cd extends-wrapper

Build

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

L’output renderizzato e il lockfile vengono generati, non forniti: questo esempio esegue il commit dei propri input e rigenera tutto il resto. --auto-pull risolve il lockfile durante il build; aggrega pull --release release-reviewed.yaml eseguito una volta in anticipo fa la stessa cosa e permette ai build successivi di essere eseguiti senza alcun flag.

Sia il wrapper sia la base che estende risiedono nel catalogo condiviso, che si risolve da hub.aggrega.ai, il registry predefinito dichiarato da .aggrega-config.yaml. Il comando di build non ha bisogno di alcun flag --catalog, e nemmeno aggrega inspect eseguito da questa directory.

Il pull recupera core/gateway/nginx perché il wrapper lo estende: una base è una dipendenza di tutto ciò che la estende, quindi il pull segue la chiave extends: del wrapper e fissa la base nel lockfile, che il Manifest la nomini o no. Qui il Manifest mappa la base per un altro motivo — il rilascio di controllo più sotto dichiara un’istanza della base stessa.

Il dist/compose/docker-compose.yaml renderizzato contiene la prova:

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]

Tre letture, in ordine di ciò che dimostrano:

  • aggrega.ai/recipe-uri: nginx:1.0.0 — la Recipe della base ha dato forma a questo servizio. L’etichetta di provenienza su un’istanza del wrapper nomina la Recipe della base perché è quella la Recipe che l’ha renderizzata.
  • location /api/ — values.upstream_path, una chiave che solo la base dichiara, scritta su un’istanza del wrapper e renderizzata.
  • proxy_pass http://internal:8081 — l’arco reviewed_upstream risolto. provides.host e provides.port del componente di destinazione sono arrivati nel contesto di iniezione sotto le chiavi di consegna che la Recipe della base legge, quindi un socket aggiunto dal wrapper passa attraverso una Recipe che non ne ha mai sentito parlare.

Il lockfile che il build risolve registra lo stesso fatto dal lato del risolutore: un’unica voce compose/nginx:1.0.0 a un unico digest, referenziata da entrambe le chiavi di mappatura — il tipo della base e quello del wrapper.

Le etichette e le annotazioni del wrapper viaggiano con l’arco risolto: il contesto di rendering di un nodo consumatore porta i provides, le labels e le annotazioni di ciascuna destinazione, quindi il contesto di edge sa che il suo upstream è audit-tier=reviewed e chi lo ha revisionato. Se qualcosa di tutto ciò compare in un artefatto renderizzato è una scelta della Recipe — queste etichette e annotazioni sono identità del componente che selettori e policy possono leggere, non output che il compilatore appone.

Con un assistente AI

Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.

Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Se la cartella dell’area di lavoro non contiene ancora una cartella `extends-wrapper`, chiama una volta lo strumento `scaffold` con `example` impostato a `extends-wrapper` e senza `dir`: scrive l’esempio in una nuova cartella `extends-wrapper`. Poi chiama lo strumento `build` con `workspace_root` impostato a `extends-wrapper`, `release` impostato a `release-reviewed.yaml`, `auto_pull` impostato a true e `write` impostato a true. Dimmi quali file ha scritto la build; si trovano in `extends-wrapper/dist/`.

Il controllo: a che cosa serve l’etichetta aggiunta

aggregate-unreviewed.yaml è aggregate-reviewed.yaml con una sola modifica — il livello interno è dichiarato come la base core/gateway/nginx nuda anziché come il wrapper — e ci si aspetta che fallisca:

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.

L’arresto è la lezione. La base soddisfa il proprio socket upstream — è component.aggrega.ai/type=server, e il livello interno è cablato attraverso quel socket esattamente nello stesso modo — ma non porta alcuna etichetta audit-tier, quindi il socket più restrittivo del wrapper la rifiuta. L’etichetta che il wrapper aggiunge è ciò che rende selezionabile una sua istanza, ed è nel selettore che lo si vede.

Vale la pena conoscere altri due arresti, ed entrambi sono lo schema che fa il proprio lavoro:

  • Un Component che dichiara extends e scrive contenuto dei pilastri sotto schema: viene rifiutato al caricamento del documento, con l’indicazione del vincolo. Lo stesso vale per uno che omette del tutto schema:. schema: inherited è l’unica forma accettata, ed è scritta anziché sottintesa, così un lettore non può mai confondere un blocco di pilastri ereditato con uno dimenticato.
  • Una chiave values che la base non dichiara viene rifiutata su un’istanza del wrapper, nel percorso in cui è stata scritta, perché il contratto applicato è quello della base.

Perché è utile

Un’organizzazione che ha scelto una forma revisionata per un componente della libreria standard ha bisogno di un posto dove conservarla. Conservati in prosa, le etichette, le annotazioni e i socket vengono riformulati in ogni Aggregate che ne ha bisogno, e divergono man mano che lo sono. Pubblicata come un Component che estende la base, la forma diventa un’entità di catalogo versionata, revisionabile e con un nome: un team che la consuma scrive type: example/gateway/nginx-reviewed e una riga di Manifest, ed eredita l’intero contratto della base insieme a ogni Recipe già scritta per essa, su ogni destinazione supportata dalla base.

Il costo del wrapper è ciò che fa funzionare tutto questo: aggiunge struttura e metadati e nient’altro. Poiché non dichiara alcun pilastro, un’istanza del wrapper e un’istanza della base vengono validate rispetto a un unico contratto, e una Recipe scritta per la base non può mai essere sorpresa da una sua specializzazione.