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

Grammatica degli URI e inventario delle stringhe di formato

Le entità di Aggrega si referenziano a vicenda tramite stringhe URI che compaiono in più posizioni di authoring distinte. La stessa forma di URI (core/postgres:1.0.0) compare in cinque o più contesti di tipo di entità, e il compilatore deduce il tipo di entità dalla posizione nello schema anziché da un sigillo o da un prefisso. Gli autori che leggono o mantengono un file YAML devono tenere a mente le regole di interpretazione basate sulla posizione per sapere se core/postgres:1.0.0 si riferisce a un tipo di Component, a un modulo Aggregate, a una Recipe, a una FeatureRecipe o a un plugin Wasm.

Questa pagina riunisce la grammatica degli URI in tutte le posizioni, le regole di precedenza per le chiavi type: con versione e senza versione ai livelli di mappatura del Manifest, le regole di inferenza delle forme abbreviate degli URI OCI e il più ampio inventario delle stringhe di formato nell’intero corpus (sintassi dei template Go, funzioni Sprig, dichiarazioni JSON Schema 2020-12, JSONPath, pattern glob, regex SemVer). Gli autori che hanno bisogno di sapere «che cosa fa Aggrega con questa stringa?» dovrebbero trovare qui la risposta.

Inferenza del tipo di entità basata sulla posizione

La stessa stringa URI assume un significato di tipo di entità diverso a seconda di dove compare nello schema. La tabella seguente elenca ogni posizione in cui Aggrega si aspetta un URI di riferimento a un’entità, insieme al tipo di entità dedotto:

PositionTipo di entità dedottoEspansione del percorso OCI
Aggregate.spec.components.<id>.typeComponent/component/{publisher}/{category}/{name}
Aggregate.spec.subsystems.<name>.components.<id>.typeComponent (come per components — i sottosistemi sono raggruppamenti di componenti)/component/{publisher}/{category}/{name}
Aggregate.spec.aggregates.<id>.typeAggregate (modulo sotto-aggregato)/aggregate/{publisher}/{name}
Aggregate.spec.components.<id>.features.<id>.typeFeature/feature/{publisher}/{name}
Aggregate.spec.components.<id>.features.<id>.typeFeature (credenziale — con etichetta feature.aggrega.ai/kind: secret)/feature/{publisher}/{name}
Manifest.spec.mappings.components.type.<key>Component (l’URI usato come chiave di ricerca); il valore è un URI di Recipechiave: /component/; valore: /recipe/{provider}/{name}
Manifest.spec.mappings.components.name.<id>Recipe (associazione granulare di override)/recipe/{provider}/{name}
Manifest.spec.mappings.features.type.<key>Feature (chiave di ricerca); il valore è un URI di FeatureRecipechiave: /feature/; valore: /featurerecipe/{provider}/{name}
Manifest.spec.mappings.features.name.<id>FeatureRecipe (associazione granulare di override)/featurerecipe/{provider}/{name}
Manifest.spec.mappings.features.annotations.<key>.featureFeature (legata a un’annotazione)/feature/{publisher}/{name}
Recipe.spec.implementsComponent (contratto di interfaccia)/component/{publisher}/{category}/{name}
FeatureRecipe.spec.implementsFeature (contratto di interfaccia)/feature/{publisher}/{name}
Component.spec.extends / Feature.spec.extendsComponent / Feature (genitore nella catena di ereditarietà)/component/{publisher}/{category}/{name} o /feature/{publisher}/{name}
Manifest.spec.extendsManifest (genitore nella catena di ereditarietà delle mappature)non è una posizione URI — un percorso relativo, o il semplice metadata.name di un Manifest accanto alla Release
Release.spec.extendsRelease (genitore nella catena di ereditarietà)non è una posizione URI — un percorso relativo a un file di Release, e nessun’altra forma
Release.spec.aggregateAggregate (il target di distribuzione della Release)/aggregate/{publisher}/{name}
Release.spec.manifestManifest (il lockfile delle mappature della Release)non è una posizione URI — un percorso relativo, o il semplice metadata.name di un Manifest accanto alla Release
FeatureRecipe.spec.pipeline.<step>.pluginplugin Wasm/plugin/{pluginType}/{name}

Tre posizioni sono elencate perché gli autori vi ricorrono aspettandosi un URI, e non lo sono. Un Manifest e una Release sono documenti del lato della distribuzione scritti l’uno accanto all’altro anziché entità indicizzate nel catalogo, quindi né l’extends: dell’uno né quello dell’altra, e nessun manifest: di una Release, viene risolto rispetto al catalogo o a un registry. Il manifest: di una Release indica un file, o il semplice metadata.name di un Manifest che si trova accanto alla Release. Nelle due posizioni extends: il valore indica un file, e una coordinata di registry scritta in una delle due viene rifiutata con la forma accettata indicata nella diagnostica. Le due posizioni extends: non si scrivono nemmeno allo stesso modo — un Manifest accetta anche il semplice metadata.name di un Manifest che si trova accanto alla Release, mentre una Release accetta il percorso relativo e nient’altro. Vedi entities/release.md per la forma della Release e errors/fatal-halts.md per ciò che dice ciascun rifiuto.

La regola di inferenza: la posizione nello schema YAML determina il tipo di entità. Non esiste alcun marcatore in superficie (sigillo, prefisso, annotazione a livello di schema) che indichi all’autore a quale tipo di entità faccia riferimento un determinato campo type:. Gli autori tengono a mente le regole basate sulla posizione quando leggono lo YAML; gli strumenti (il completamento dell’editor, aggrega inspect) leggono le stesse regole per proporre suggerimenti specifici per il tipo di entità.

Due forme di URI — plugin a coordinate derivate ed entità di catalogo con il tipo nei metadati

Un URI di entità di catalogo non porta alcun sigillo di tipo (la sezione precedente). Gli URI dei Plugin sono il contrappunto voluto: un URI di plugin riporta invece un segmento di classificazione — il suo tipo di socket — direttamente nel percorso. Le due famiglie di riferimenti si leggono in modo diverso di proposito, e sapere a quale famiglia appartiene un URI ti dice dove cercarne la classificazione.

Le coordinate dei Plugin derivano dal tipo del plugin. Un riferimento a un plugin è oci://hub.aggrega.ai/plugin/<pluginType>/<name>. La coordinata è derivata: il segmento <pluginType> e il semplice <name> provengono dal blocco di indirizzamento del plugin — metadata.pluginType e metadata.name — composti nel percorso. Il socket non è codificato come percorso nel nome; metadata.name è semplice. La coordinata derivata È la chiave del registry (e dell’insieme dei plugin incorporati), quindi il registry organizza i plugin per socket. I plugin di base si risolvono in coordinate come plugin/provider/helm, plugin/linter/publishing e plugin/parser/yaml — ciascuna la composizione di un semplice metadata.name (helm, publishing, yaml) con il suo metadata.pluginType (provider, linter, parser). Il segmento <pluginType> è esattamente il tipo di socket del plugin: lo stesso semplice <name> sotto un pluginType diverso è un plugin diverso, perché la coordinata derivata — e quindi l’identità — è diversa. Per la tassonomia completa dei socket rispetto alla quale classifica il segmento <pluginType>, vedi entities/plugin.md.

Le entità di catalogo portano il tipo nei metadati. Il riferimento scritto dall’autore è <publisher>/<category>/<name> (ad esempio, core/datastore/postgres). Il kind: dell’entità si trova nel file; il tipo di entità dell’URI viene dedotto dalla posizione nello schema, secondo Inferenza del tipo di entità basata sulla posizione più sopra. Il percorso è organizzato per categoria, non per tipo: un Component porta un segmento di categoria (core/datastore/postgres); una Recipe o una FeatureRecipe porta la propria capacità di rendering come primo segmento (helm/postgres); i tipi restanti sono piatti, <publisher>/<name>. Nulla nel percorso scrive il tipo di entità.

Perché le due forme differiscono. I Plugins sono organizzati nel registry per socket, quindi il segmento del socket è la chiave naturale del registry ed è presente in ogni URI di plugin. Le entità di catalogo sono organizzate nel registry per categoria, quindi è la categoria — non il tipo — ciò che il percorso scrive. Un URI ti dice quindi il socket di un plugin dal solo percorso, ma ti dice il tipo di un’entità di catalogo solo dopo che hai letto il file (il tipo si trova in metadata, la posizione lo fornisce in un punto di riferimento). Questa asimmetria è intenzionale: il percorso di ciascuna famiglia rispecchia il modo in cui quella famiglia è organizzata nel registry, non un’unica grammatica uniforme imposta a entrambe.

Forma dell’URI — con versione e senza versione

Ogni posizione URI sopra indicata accetta un riferimento in una di tre forme — senza versione, oppure con un pin dopo i due punti, con una versione esatta o un intervallo con caret:

FormaEsempioSemantica
Senza versionecore/postgresSi risolve in «qualsiasi versione» o nell’«ultima registrata», a seconda della semantica di risoluzione della posizione
Pin esattocore/postgres:1.0.0Fissa una versione specifica. La versione è una versione semantica, la forma che assume il metadata.version di ogni entità
Pin con caretcore/postgres:^1.0.0Seleziona la versione più alta compatibile con quella indicata — per ^1.0.0, pari o superiore a 1.0.0 e inferiore a 2.0.0

Il pin è il testo dopo gli ultimi due punti del riferimento, e solo quando quel testo non contiene alcun /. Un riferimento a un host di registry con una porta — localhost:5000/core/postgres — quindi non porta alcun pin: il testo dopo i due punti della porta continua il riferimento.

Un pin che non ha nessuna di queste forme — un caret il cui testo non si legge come un intervallo di versioni (core/postgres:^garbage), o un pin esatto che non è una versione semantica (core/postgres:1.x, core/postgres:1.0, core/postgres:v1.0.0) — non indica alcuna versione. Quando un comando risolve un tale riferimento e questo non si risolve, il rifiuto indica il riferimento, il pin e le tre forme sopra, anziché segnalare un’entità o una versione che il catalogo non contiene; la diagnostica è descritta in errors/fatal-halts.md sotto «A version pin is none of the forms a pin takes (Un pin di versione non ha nessuna delle forme che un pin assume)». Il pin viene valutato solo lì, quindi un pin malformato non cambia mai quali riferimenti si risolvono, e un pin ben formato che nessuna versione disponibile soddisfa viene segnalato come tale. Nessuno schema definisce la grammatica del pin, quindi un pin malformato viene segnalato quando qualcosa risolve il riferimento — aggrega validate, aggrega pull, aggrega build — anziché quando il file viene caricato.

Le forme coesistono nella stessa posizione. Gli autori scelgono in base al fatto che abbiano bisogno di fissare la versione o di flessibilità sulla versione. Il livello mappings.{components,features}.type del Manifest supporta entrambe le varianti come chiavi distinte del dizionario, con la precedenza la chiave con versione prevale su quella senza versione — una chiave con versione (core/api-server:1.0.0) ha la precedenza sulla chiave senza versione (core/api-server) quando entrambe corrispondono alla stessa ricerca. Le due varianti non si escludono a vicenda; entrambe possono stare nella stessa mappa type: e il resolver sceglie la più specifica. Il dispatch del Provider deriva dal campo spec.capability della Recipe risolta, quindi il Manifest mappa un tipo a una Recipe e nient’altro.

Per il regime di consumo delle versioni per entità (quali entità hanno effettivamente il proprio campo di versione consumato dal dispatch della risoluzione e quali come provenienza descrittiva), vedi vocabulary/inheritance-and-interface.md «Cross-entity version consumption (Consumo delle versioni tra entità)».

Un riferimento a un Component, a una Feature, a un Aggregate o a un Plugin accetta anche un intervallo con caret (core/postgres:^1.0.0) e, qualunque forma assuma, seleziona la versione più alta che lo soddisfa tra quelle che il catalogo contiene, secondo un’unica regola che ogni comando applica — vedi version-resolution.md. Per la corrispondenza a tre forme di implements:, che è il controllo di coerenza su una mappatura anziché una selezione, vedi 10-status.md «Version matching (Corrispondenza delle versioni)».

Identità, non ubicazione

Un riferimento canonico a un’entità — compreso un riferimento a un plugin — è un’identità, non un’ubicazione: indica che cosa è l’entità, mai dove si trova attualmente.

L’identità è semplice e priva di host. Non porta alcun host di registry; l’host è una coordinata di risoluzione fornita dalla configurazione tramite default_registry e associata al momento della risoluzione. Spostare un registry, o replicare la stessa entità altrove, è una modifica di configurazione — i riferimenti che indicano l’entità restano invariati.

L’identità è anche priva di versione. Un riferimento può portare un pin di versione facoltativo (:<version> o :^<version>) per vincolare quali versioni lo soddisfano, e ogni Release registra la versione esatta risolta come pin nel proprio lockfile, ma la versione viene fornita accanto all’identità anziché esservi incorporata.

Al momento della risoluzione il compilatore unisce l’identità semplice all’host configurato e alla versione fissata per arrivare a byte concreti. Poiché entrambi sono forniti separatamente, lo stesso riferimento si risolve rispetto a un registry diverso o a una versione fissata diversa senza alcuna modifica al sorgente che lo indica.

Inferenza delle forme abbreviate degli URI OCI

Gli autori non devono scrivere ogni URI come URI OCI completamente qualificato. Il compilatore applica quattro regole di inferenza ortogonali per espandere le forme abbreviate di authoring in URI OCI canonici al momento della risoluzione. Le regole:

Regola 1 — Dominio predefinito

A qualsiasi URI privo di dominio viene anteposto il default_registry configurato in .aggrega-config.yaml (predefinito: hub.aggrega.ai/).

# Shorthand
type: core/postgres:1.0.0
# Equivalent canonical form
type: hub.aggrega.ai/component/core/postgres:1.0.0

Regola 2 — Espansione contestuale dell’entità

Il compilatore aggiunge il segmento corretto del tipo di entità in base alla posizione nello schema. La mappatura è la stessa della tabella di inferenza per posizione più sopra (/component/, /aggregate/, /recipe/, /featurerecipe/, /feature/, /plugin/).

# Same string, two positions, two expansions
Aggregate.spec.components.foo.type: core/postgres:1.0.0
# → hub.aggrega.ai/component/core/postgres:1.0.0
Manifest.spec.mappings.components.type."core/postgres:1.0.0": helm/postgres:1.0.0
# Key: hub.aggrega.ai/component/core/postgres:1.0.0
# Value: hub.aggrega.ai/recipe/helm/postgres:1.0.0

Regola 3 — Precedenza a tre livelli

Prima di applicare l’inferenza OCI, il compilatore risolve l’URI tramite il modello di risoluzione delle entità a tre livelli documentato in architecture/13-catalog-and-registry.md:

  1. Percorso locale — per i documenti che una Release e il suo Manifest indicano. L’aggregate, il manifest o l’extends di una Release, o l’extends di un Manifest, scritti con un prefisso ./ o ../ vengono letti come file relativo alla directory della Release stessa; l’inferenza OCI non viene eseguita. Nessun’altra posizione accetta un percorso: un type, una chiave o un valore di mappatura del Manifest, un implements o un plugin di pipeline scritti come ./… non indicano alcuna entità e arrestano la build. Un’entità scritta localmente si colloca sotto catalog/ alla radice del workspace o in una directory elencata da workspace.catalog_dirs, e si risolve per nome attraverso il livello del workspace e della cache.
  2. Workspace e cache — lo stack di ricerca del catalogo del workspace, poi la cache. Le directory catalog_dirs: del workspace di .aggrega-config.yaml — o, per una Release a cui la configurazione assegna directory proprie sotto workspace.releases, quelle di quella Release — vengono cercate nell’ordine in cui sono scritte, e la directory catalog/ della radice del workspace viene cercata per ultima — dopo ogni voce elencata, e solo quando quella directory esiste. Una corrispondenza in qualsiasi punto dello stack interrompe l’inferenza OCI. Un mancato riscontro consulta poi artifact_cache_dir, che contiene ciò che i precedenti pull dal registry hanno recuperato.
  3. Registry. Quando il livello del workspace e della cache non trova corrispondenze, si applicano le regole di inferenza OCI e il riferimento viene recuperato dal registry remoto da aggrega pull, o da una build eseguita con --auto-pull o con l’impostazione auto_pull del workspace; una build senza nessuno dei due legge solo ciò che il suo lockfile fissa.

La cascata consente a un progetto di combinare i documenti che una Release indica per percorso (il livello del percorso locale) con il contenuto di catalogo copiato nel repository e locale al workspace (il livello del workspace e della cache) e con il contenuto del registry recuperato da remoto (il livello del registry), e un riferimento a un’entità si scrive allo stesso modo qualunque dei due ultimi livelli contenga l’entità.

Quando catalog_dirs: elenca più di una directory, l’elenco è uno stack di precedenza ordinato in cui vince il primo: un’identità di entità presente in più di una directory elencata si risolve nella directory elencata per prima, e l’occorrenza successiva viene oscurata (sovrascritta, non è un errore) — così un progetto può anteporre la propria directory di catalogo a una condivisa e sovrascrivere entità per identità, mentre le restanti ricadono su quella condivisa. La sovrascrittura viene riportata nel dettaglio della risoluzione. Due file che rivendicano la stessa identità all’interno di una singola directory restano un errore di authoring che arresta il caricamento.

La directory catalog/ della radice del workspace si trova alla fine di quello stack anziché in cima, quindi qualsiasi cosa un progetto elenchi prevale su di essa in caso di collisione, ed elencare una directory non correlata non impedisce mai che venga letta. Viene saltata quando una voce elencata la raggiunge già — la scansione di una directory elencata è ricorsiva, quindi uno stack che indica la radice del workspace l’ha già letta. Omettere catalog_dirs: e scriverlo come elenco vuoto sono affermazioni diverse: se omesso, il workspace legge comunque catalog/; se scritto come [], non legge alcun catalogo locale, ed è così che un workspace dichiara di non averne.

Regola 4 — Gestione della versione

Un URI può includere od omettere il segmento di versione. La gestione della versione dipende dalla posizione di risoluzione (risoluzione del livello del Manifest, corrispondenza di implements:, importazione di sotto-aggregati) secondo le regole di consumo delle versioni proprie della posizione. Vedi inheritance-and-interface.md «Cross-entity version consumption (Consumo delle versioni tra entità)» per la semantica delle versioni per entità.

Inventario delle stringhe di formato

Oltre alle stringhe URI, la superficie di authoring di Aggrega comprende diverse convenzioni distinte di stringhe di formato. Gli autori che scrivono o leggono file YAML incontrano i seguenti formati in posizioni diverse:

FormatoDove viene scrittoValidato da
Template Go ({{ .field }})Recipe valuesMapping: / workload: / artifacts: / provides: / locals: / source:; FeatureRecipe injectMapping: / with: della pipeline; interpolazione di parameters: nell’Aggregate; Release directory: / subDirectory:Parser dei template Go al momento della valutazione; regole di disponibilità per sito in templates/expansion-matrix.md
Riferimento alle funzioni Sprig ({{ default 1 .v }} ecc.)Le stesse superfici dei template GoFuncMap di Sprig v3 registrata all’inizializzazione del motore di template; elenco completo degli helper in templates/sprig-functions.md
JSON Schema 2020-12 (forma compatta o completa)Contenuto schema: di Component / Feature (o un $ref: a una voce di una SchemaLibrary)Validatore JSON Schema al caricamento dell’entità durante la risoluzione
JSON Pointer (RFC 6901)Chiavi locals.<*_path>: della Recipe (volumes_path, containers_path, ecc.); riferimenti all’output dei passi di pipeline: della FeatureRecipe; payload JSONPatch dei plugin WasmBase RFC 6901 secondo il contratto dei plugin Wasm; dichiarata in plugins/plugin-contract.md
Regex SemVerCampi metadata.version su ogni entitàRegex JSON Schema ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-...)?$ per schema di entità
Pin di versione (:<version>, :^<version>)Il segmento di versione di un riferimento a un’entità, in ogni posizione URI sopra indicataIl compilatore, quando risolve il riferimento: un pin esatto è una versione semantica e l’intervallo di un pin con caret viene analizzato, e un pin malformato viene rifiutato con la propria condizione — vedi Forma dell’URI più sopra
Percorso del filesystemPercorsi relativi al catalogo (ad es. le voci catalog_dirs: di .aggrega-config.yaml); percorsi di file $import: della Recipe in workload: / artifacts: / valuesMapping:Letto così come è scritto al momento della risoluzione — una voce catalog_dirs: relativa al file di configurazione che la dichiara, un percorso $import: relativo alla directory dell’entità stessa; nessun glob viene espanso, quindi un * indica un file o una directory con quel nome
Espressione del selettore di etichetteComponent.spec.usesSchema.<socket>.selector; appliesTo: / appliesToAnyOf: della FeatureParser dei selettori di Aggrega nel punto in cui il selettore viene valutato; grammatica dei selettori documentata in vocabulary/modifier-system.md
Forma della chiave di annotazione (<namespace>/<name>)Chiavi metadata.annotations; chiavi features.annotations del Manifest; cascata delle annotazioni del confineRegex JSON Schema per entità; disciplina dei prefissi riservati in vocabulary/labels-and-annotations.md
Nome del Provider, facoltativamente con pin di versione (helm, helm:^1.0.0)Recipe.spec.capability; FeatureRecipe.spec.capabilityRicerca per il dispatch del Provider; un pin che nessuna versione del plugin soddisfa arresta la build
Chiave di consegna di inject (env.<KEY>, file.<path>, arg.<flag>)Blocchi inject: dell’Aggregate; output di injectMapping: della FeatureRecipeSchema di inject in vocabulary/topology-triad.md

Ogni formato ha la propria grammatica, il proprio validatore e la propria forma di segnalazione degli errori. Gli autori che incontrano un errore di analisi di una stringa di formato leggono il riferimento del singolo formato per le regole di sintassi.

L’editor segnala questi errori mentre scrivi: aggrega serve valida ogni documento che riceve rispetto allo schema del suo tipo e restituisce lo stesso verdetto che darebbe una build (vedi cli/aggrega-serve.md «Live validation (Validazione in tempo reale)»), e aggrega scaffold prepara la bozza di un documento iniziale di qualsiasi tipo.

Riferimenti incrociati