Versione 1.0.0-alpha.1ultima
Capitolo 2.21
Il Plugin SDK
Installazione del Plugin SDK (software development kit), i suoi strumenti da riga di comando, una panoramica del modello full-service, il manifest v2 campo per campo e i ventidue controlli che vincolano un plugin alle regole.
Questa pagina è stata tradotta dall'IA a partire dall'originale in inglese. In caso di dubbi, fa fede la pagina in inglese. Legga questa pagina in inglese

Il mio secondo plugin ha richiesto un terzo del tempo rispetto al primo, e quasi tutto il risparmio è stato merito dell'SDK (software development kit). La prima volta ho scritto un controllo di ambito, un caricatore di configurazione e un esecutore di migrazione, e un revisore me li ha rimandati indietro tutti. La seconda volta ho eseguito un solo comando di scaffolding, ho eliminato la skill di esempio per l'analisi del sentiment e ho dedicato le mie giornate ai record di revisione delle anomalie di cui il nostro team di dinamica del volo aveva effettivamente bisogno.
@adverant-nexus/plugin-sdk è un unico pacchetto npm. Contiene lo schema del manifest v2 e i validatori che lo leggono (definePlugin, defineSkill), i moduli runtime che il plugin importa per ambito, database, dispatch e il resto, gli helper di test, i gate di conformità e gli strumenti a riga di comando. Questo capitolo illustra l'installazione, gli strumenti, il template, il manifest e i gate. Il Capitolo 2.22, Il runtime del plugin, tratta i moduli runtime nel codice in esecuzione.
Installazione
Il pacchetto proviene dal registro di Adverant all'indirizzo https://registry.adverant.ai/npm/, mai dal registro pubblico di npm, ed è necessario il pull token dalla pagina "Pull token e comandi di installazione" del proprio account. Puntare lo scope @adverant-nexus al registro nel file .npmrc del repository:
@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>
<pull-token> è il token presente nella pagina dell'account. In una pipeline, passarlo da un secret e non effettuarne mai il commit; il Dockerfile del template rifiuta la build se manca ed elimina .npmrc dalla fase di build una volta eseguito npm ci, in modo che il token non venga mai incluso in un'immagine.
Quindi bloccare la versione esatta:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Effettuare il commit di package-lock.json alla prima installazione. La build dell'immagine del template esegue npm ci e rifiuta di ripiegare su npm install: il lockfile costituisce il contratto. Il requisito minimo dell'SDK è Node 18; il template è destinato a Node 20.
Gli strumenti a riga di comando sono inclusi nel pacchetto, pertanto ogni comando in questa documentazione indica il pacchetto e la relativa versione con npx -p. Da solo, npx create-nexus-plugin viene cercato nel registro pubblico e quel nome non corrisponde a questo pacchetto.
Gli strumenti da riga di comando
| Strumento | Cosa fa |
|---|---|
create-nexus-plugin |
Esegue lo scaffolding di un plugin, convalida un manifest, migra un manifest v1 a v2 e genera la guida per il consumatore destinata allo sviluppatore frontend |
nexus-tenancy |
Genera l'SQL di tenancy dello schema a partire dal manifest: ruoli, concessioni, il template di row-level security e le tabelle del grafo |
nexus-migrate |
Applica le migrazioni: effettua il provisioning dei ruoli una sola volta, quindi esegue ogni file numerato con il ruolo di migratore |
nexus-gates |
Esegue ogni gate di conformità e il relativo autotest |
create-nexus-plugin non effettua alcuna chiamata di rete e non carica codice remoto. Esegue gli stessi validatori in-process utilizzati dall'onboarding della piattaforma, evitando così qualsiasi discrepanza tra "convalidato sulla mia macchina" e "accettato dalla piattaforma".
| Comando | Flag | Cosa fa | Codici di uscita |
|---|---|---|---|
scaffold <name> |
--tier full-service\|ui-only\|skills-only, --dir <path>, --print |
Scrive una nuova directory del plugin; --print stampa solo il manifest |
0 scritto · 1 sovrascrittura rifiutata · 2 utilizzo errato |
validate <file> |
Convalida un nexus.manifest.json, oppure un modulo .ts o .js che ne esporta uno |
0 valido · 1 non valido o illeggibile · 2 utilizzo errato | |
migrate <file> |
--write |
Aggiorna un manifest v1 a v2 e lo stampa, oppure lo sovrascrive sul posto | 0 · 1 · 2, come sopra |
guide |
--manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint |
Genera la guida per il consumatore dal manifest e dal testo descrittivo; --check confronta con la copia sottoposta a commit e non scrive nulla |
0 · 1 discrepanza o violazione di linting · 2 utilizzo errato |
help |
Stampa le istruzioni d'uso | 0 |
Scaffolding e i tre livelli
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-service--tier ha come valore predefinito full-service. Lo scaffolder rifiuta di scrivere in una directory già esistente e il manifest che scrive supera già la convalida; non ne emette mai uno non valido.
Scegliere il livello in base a ciò che contiene il plugin.
| Livello | Contiene | Deve dichiarare |
|---|---|---|
skills-only |
Skill del manifest e nient'altro | skills[], con almeno una voce |
ui-only |
Una superficie frontend all'interno della shell | frontend |
full-service |
Un backend e un frontend, solitamente con un proprio schema | backend e frontend; e poiché ha un backend, runtime.healthCheck |
In caso di dubbio, eseguire lo scaffolding di full-service ed eliminare ciò che non serve. Procedere in senso inverso significa dover scrivere le parti che il template avrebbe già fornito.
Panoramica del modello full-service
Il template è il plugin di riferimento, costruito secondo il rigoroso pattern dato per scontato in ogni capitolo successivo. Clonarne la struttura, non la logica di esempio.
| Percorso | Cos'è |
|---|---|
nexus.manifest.json |
Il manifest v2: le tre leggi riaffermate, la tabella delle route e il relativo registro dei diritti |
src/config.ts |
Il caricatore di configurazione. Una sola specifica, letta una volta, ogni problema raccolto prima che il processo rifiuti di avviarsi |
src/scope.ts |
L'unico file che trasforma una richiesta in un ambito, con il verificatore rigoroso dei token dell'SDK e due regimi: il bearer token di una persona e la chiamata di servizio della piattaforma |
src/db.ts |
Ogni istruzione compone tenantFence() e viene eseguita all'interno di withScopedTx |
src/uno.ts |
L'unico file di dispatch: un URL, un client, una allow-list chiusa |
src/routes/*.ts |
health (anonimo, percorso esatto), le route /api (con ambito) e il callback /internal (protetto da servizio) |
src/skills/sentiment.ts |
Una skill host_callback deterministica; sostituire il lessico con la propria logica |
src/server.ts |
La radice di composizione: installa il registro dei rifiuti una volta, attende il database (con limite di tempo), quindi esegue i controlli di isolamento e del registro prima di mettersi in ascolto |
migrations/000_tenancy.sql |
Generato da nexus-tenancy render al momento dello scaffolding: ruoli, schema, il template di row-level security |
migrations/001_init.sql |
Due tabelle con una chiave composta che inizia con il tenant e una chiave esterna composta che trasporta il tenant |
migrations/002_refusal_ledger.sql |
La tabella scritta dal registro dei rifiuti |
scripts/ci/required-env |
Stampa in formato JSON i nomi delle variabili d'ambiente richieste all'avvio |
scripts/ci/shadow-migrate-*.sh |
La simulazione (dry run) di migrazione della pipeline, tramite nexus-migrate |
gates/ |
La directory delle esenzioni dei gate: vuota, che è lo stato corretto per un nuovo plugin |
test/ |
Test per ambito, route, database, dispatch e avvio, con i test double di ambito iniettati da ogni test |
Dockerfile |
Un'immagine non-root (ID utente 10001) con le migrazioni al suo interno |
Alcuni di questi file meritano un esame più approfondito.
src/config.ts segue due regole. Raccoglie ogni problema prima di sollevare un'eccezione, in modo che un singolo riavvio elenchi tutte le cinque variabili mancanti invece di avere cinque riavvii che ne indicano una ciascuno. Inoltre, assegna un valore predefinito solo quando un valore errato non può produrre una risposta errata silenziosa: PORT può avere 8080 come valore predefinito, poiché una porta errata fa fallire il bind in modo visibile, mentre DATABASE_URL e UNO_DISPATCH_URL sono obbligatori e devono essere indirizzi interni al cluster. Un indirizzo pubblico viene rifiutato all'avvio.
node scripts/ci/required-env["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]
Il test stesso del template esegue quel file e ne confronta l'output con i nomi che la specifica di configurazione contrassegna come obbligatori; pertanto, l'aggiunta di una variabile obbligatoria senza aggiornare l'elenco fa fallire npm test.
src/server.ts non si mette in ascolto finché il database non risponde e limita l'attesa a 120 secondi, registrando ogni tentativo fallito con la relativa causa. Successivamente dimostra, nell'ordine, che il ruolo dell'app non può riassegnare il tenant e che ogni tabella è sottoposta forzatamente a row-level security, che il pool di ciascun pod rientra nel limite di connessioni del ruolo e che la tabella del registro dei rifiuti può accettare una riga. Un rifiuto da parte di uno qualsiasi dei tre viene stampato per intero e il processo termina con codice 2.
Il manifest v2, campo per campo
Il manifest è il contratto leggibile dalla macchina tra il plugin e la piattaforma. Viene convalidato durante la stesura, al momento dell'onboarding sulla piattaforma e in modo continuo in seguito. Lo schema è additionalProperties: false a ogni livello: se il plugin ha una sezione, esiste una proprietà apposita e una chiave non dichiarata viene rifiutata. La soluzione consiste sempre nell'utilizzare la proprietà opzionale corretta.
Il nucleo obbligatorio
| Campo | Regola |
|---|---|
manifestVersion |
Esattamente "2". Un documento v1 viene migrato, mai riconvalidato sul posto |
name |
^[a-z0-9]+([-.][a-z0-9]+)*$, al massimo 64 caratteri. L'ID del plugin utilizzato nella registrazione, nel namespacing del dispatch e nelle righe con ambito tenant. Un plugin che dichiara delle skill richiede anche un nome senza punti e senza cifre iniziali |
displayName |
Da 1 a 120 caratteri |
version |
Versione semantica; il proprio ciclo di rilascio |
description, author, license |
Almeno un carattere ciascuno |
tier |
skills-only, ui-only o full-service |
trust |
core, verified, community o untrusted |
runtime |
Obbligatori: executionMode, isolationLevel (da 1 a 4), entrypoint. Opzionali: nodeVersion, healthCheck, readinessCheck, livenessCheck, ciascuno un percorso che inizia con /. La modalità deriva dal livello: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker |
architecture |
compute, ai e deploy, le tre leggi della piattaforma riaffermate. Il validatore impone la formulazione esatta |
Per un plugin realizzato per la propria installazione, le tre frasi sono le seguenti. La frase ai riguarda l'intelligenza artificiale (IA) ed è il punto in cui dichiarare che il plugin non detiene credenziali di modelli.
"architecture": {
"compute": "All compute runs via UNO dispatch (nexus-orchestrator /api/v1/dispatch + nexus-workflows). No direct engine, queue or model-provider calls from plugin code.",
"ai": "All AI goes through the AI Provider Router, which alone owns the credential and the final provider/model decision. This plugin holds no model credentials.",
"deploy": "Deploy is through the installation's release channels only."
}La tabella delle route: api e rights
api richiede version e basePath, e opzionalmente websocket (path, auth) e endpoints[]. La tabella delle route è il concetto più solido dello schema: un gate ne confronta le differenze rispetto alle route effettivamente registrate dal codice, in entrambe le direzioni, rendendo il manifest un contratto verificabile e non semplice documentazione.
Ogni endpoint richiede method (GET, POST, PUT, PATCH o DELETE) e path. Il resto:
| Campo | Cosa indica |
|---|---|
auth |
Una di cinque classi: scope (la route di una persona, dietro la guardia di ambito), service-key e internal (server-to-server, mai raggiungibile da un browser), public (esclusivamente un percorso esatto con allowAnonymous) e device (una macchina con una propria credenziale, dietro la guardia del dispositivo) |
right |
Obbligatorio su ogni route servita dalla guardia di ambito e rifiutato su qualsiasi altra: il nome di un diritto nel registro rights |
needsUnit |
La route rifiuta la richiesta quando l'unità del chiamante non può essere risolta |
allowAnonymous |
Solo allow-list a corrispondenza esatta. Una regola basata su prefisso è il modo in cui /health-of-tenant-42 finisce per diventare pubblico |
group, serves, screens |
Sotto un blocco release: il gruppo di capacità servito dalla route, ciò che risponde quando la funzionalità con licenza di quel gruppo è bloccata (data, teaser, sighting o ask) e le schermate che serve |
query |
required (ogni nome con un valore di esempio) e allowed: i parametri di query letti dalla route |
body |
example: il corpo di esempio di una route di scrittura, accettato dal suo stesso validatore. Mai su una GET |
rights è il registro a cui fanno riferimento tali route. Ogni diritto ha roles (il tetto massimo) e opzionalmente summary, never (ruoli che non possono mai esercitarlo, indipendentemente da ciò che detengono), barred (le parole specifiche del prodotto per rifiutare un ruolo never), seat (è necessaria anche una postazione attiva), self (ogni persona verificata lo detiene, per i diritti sulla propria sessione), grants (i titolari assegnano le postazioni; al massimo un diritto lo dichiara), licence (una funzionalità soggetta a licenza che la licenza dell'organizzazione deve includere), installation (detenuto solo dagli amministratori dell'installazione stessa) e platform (detenuto solo dagli amministratori della piattaforma di Adverant; non nomina ruoli). I nomi dei diritti contengono almeno un punto: project.read, money.pay.
"api": {
"version": "1",
"basePath": "/",
"endpoints": [
{ "method": "GET", "path": "/health", "summary": "Liveness", "auth": "public", "allowAnonymous": true },
{ "method": "GET", "path": "/api/projects", "summary": "List the caller's projects", "auth": "scope", "right": "project.read" },
{ "method": "POST", "path": "/api/projects", "summary": "Create a project", "auth": "scope", "right": "project.create" },
{ "method": "POST", "path": "/internal/skills/sentiment_score", "summary": "host_callback receiver", "auth": "service-key" }
]
},
"rights": {
"project.read": { "summary": "Read the organisation's projects.", "roles": ["owner", "admin", "member", "viewer"] },
"project.create": { "summary": "Open a project.", "roles": ["owner", "admin", "member"] }
}definePlugin rifiuta una route di ambito priva di diritto (ENDPOINT_RIGHT_MISSING), un diritto assente dal registro (ENDPOINT_RIGHT_NOT_REGISTERED) e un diritto su una route non servita da alcuna guardia (ENDPOINT_RIGHT_UNGUARDED). Rifiuta inoltre un registro che si contraddice e due diverse grafie di una stessa route (:id e :recordId) come DUPLICATE_ENDPOINT.
I dati: databases, schema e db
schema è l'unico schema Postgres di proprietà del plugin. public, plugins, auth e nexus sono vietati e, se anche databases[] nomina uno schema Postgres, i due devono coincidere.
databases[] dichiara ogni archivio in base al motore: postgresql (schema, tables, migrations e granted, le tabelle che un'altra organizzazione può leggere in virtù di una concessione registrata), neo4j (schemas), qdrant (collections) o redis (purpose).
db contiene i limiti di sessione per ogni connessione aperta dal plugin, dichiarati qui anziché nel codice, in modo che sia un revisore sia il deployment possano leggerli:
| Campo | Cosa limita |
|---|---|
maxConnections |
Il pool per replica |
pods |
Il numero massimo di pod che detengono un pool contemporaneamente, pari alle repliche più il picco (surge) di un aggiornamento graduale. Il limite di connessioni di ciascun ruolo viene generato come maxConnections × pods; se omesso, definePlugin emette l'avviso DB_PODS_UNDECLARED |
statementTimeoutMs |
Una singola istruzione |
idleInTransactionTimeoutMs |
Una transazione aperta che non sta eseguendo nulla |
workMemKB |
Un singolo nodo di ordinamento o di hash, per nodo e non per query |
piiMask[] |
Voci table.column contenenti dati personali, mascherate nella console SQL governata e nei log |
Skill e strumenti: skills, mcpTools, entitlements
skills[] contiene le skill del manifest; il capitolo 2.20, Skill, ne illustra i campi e i livelli. mcpTools[] contiene gli strumenti MCP (Model Context Protocol) pubblicati dal plugin, ciascuno costituito da name, description e inputSchema senza oneOf, allOf o anyOf di primo livello.
entitlements richiede featureIdPattern e accetta alwaysOn[], source e store. Il pattern indica il namespace in cui risiedono gli ID delle funzionalità, per convenzione il name del plugin più un segmento compilato dal codice per ciascuna superficie. alwaysOn[] è il breve elenco esatto che deve rispondere anche quando non è possibile ottenere un verdetto sulle abilitazioni: stato di integrità (health), prontezza (readiness), accesso e le impostazioni necessarie a un amministratore per ripristinare l'abilitazione.
Controllo delle modifiche: changePolicy
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Le approvazioni vengono conteggiate su persone distinte, e chi ha proposto la modifica non rientra mai tra queste; senza entrambe le condizioni, "due approvazioni" si ridurrebbe a una sola persona che fa clic due volte. enabled: true richiede classes e ogni classe nominata necessita del proprio conteggio. Una classe omessa risulta non governata, il che rappresenta una scelta legittima che lo schema impone di mettere per iscritto.
Identità: domains, branding, routing
domains[] (ciascuno con primary e aliases[]; domain è la forma a dominio singolo) elenca dove risponde il plugin. branding richiede appName e accetta tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId e gaId. Tutto ciò che si trova in branding è pubblico: la pagina di accesso lo legge prima che chiunque disponga di una credenziale, pertanto non contiene mai un secret o un indirizzo interno. routing (type, gateway, virtualService) è destinato ai plugin che descrivono il proprio routing.
Dimensionamento e il resto
resources richiede cpuMillicores (da 10 a 64.000) e memoryMB (da 16 a 262.144), e accetta diskGB, timeoutMs, port e wsPort. backend contiene port, healthPath, apiPrefix, framework e platformClients[], i client SDK che il backend importa per nome. L'elenco è chiuso e un gate lo verifica rispetto alle importazioni effettive. Lo schema consente quattordici nomi: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin e uno, più uno per il client che risponde ai rifiuti di abilitazione del piano, che mantiene un nome interno. Il client per l'abilitazione delle funzionalità, runtime/entitlements, non rientra tra questi e non va mai inserito nell'elenco, poiché è già dichiarato dal blocco entitlements, e un backend che lo importa senza un blocco entitlements non supera lo stesso gate. frontend contiene basePath, mountPath e framework. nexus contiene minVersion, maxVersion, capabilities[] e permissions[].
I blocchi rimanenti svolgono ciascuno una specifica funzione:
| Blocco | Funzione |
|---|---|
settings |
Le impostazioni sul framework condiviso: groups e keys, configurate ai livelli indicati da ciascuno |
people |
sweep (service, port): i membri dell'organizzazione, sincronizzati dal servizio di identità, con disattivazione delle postazioni quando qualcuno lascia l'organizzazione |
ontology |
entityTypes e relationshipTypes: il grafo tipizzato mantenuto nel proprio schema |
release |
groups e frame: i gruppi di capacità in cui sono suddivise le route, rilasciati inizialmente come canary |
cells[] |
Un plugin costituito da più unità distribuibili: name, kind, entrypoint, port, wsPort ciascuno |
pricing |
model, currency, tiers[] per la voce di catalogo |
marketplace |
category, icon, screenshots, documentation, featured |
compliance |
instruments[], dataResidency, sovereignty |
developer, repository, keywords |
Chi lo pubblica e dove risiede il relativo codice |
metrics, atlas |
I due oggetti lasciati intenzionalmente aperti, per i nomi delle proprie metriche e la generazione della documentazione dell'architettura |
Ciò che lo schema non può esprimere
Il JSON Schema definisce la struttura; definePlugin aggiunge le regole che uno schema non può esprimere. Il classification di una skill non può superare il tetto massimo di fiducia. Solo i plugin core e verified possono dichiarare skill tool_using e llm_only. Ogni percorso dichiarato deve essere relativo e same-origin, privo di schema, di // e di barra rovesciata, poiché il parser URL converte \ in / e /\evil.example/x si risolve in cross-origin. Ogni regola applicata dalla sincronizzazione del registro a una skill viene applicata prima qui, con lo stesso codice della sincronizzazione, in modo che validate e la sincronizzazione identifichino una regola violata allo stesso modo.
Convalida e passaggio dalla v1
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json✔ anomaly-review@0.3.0 · tier=full-service · trust=community · skills=1 · mcpTools=0
Un errore stampa il percorso preciso e, per una regola di sincronizzazione, prima il codice. Si consiglia di configurarlo come commit hook.
Un manifest v1 viene aggiornato meccanicamente. migrate aggiunge le tre frasi di legge, sposta domain in domains[] e rifiuta di inventare un entrypoint non presente in origine. Convalida il risultato prima di stampare o scrivere qualsiasi cosa, in modo che una migrazione non trasferisca mai un errore dallo strumento al repository.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --writeLeggere il diff prima di effettuare il commit. Le frasi di legge aggiunte corrispondono alla formulazione esatta imposta dal validatore; per la propria installazione, impostare deploy sulla frase mostrata in precedenza.
Rendering della tenancy e provisioning dei ruoli
Non si scrivono mai a mano le concessioni dei ruoli o il template di row-level security. nexus-tenancy render li genera a partire da schema e db del manifest:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sqlIl file generato crea cinque ruoli per lo schema, ciascuno con ciò che non deve detenere: un migratore che può solo assumere il ruolo di proprietario, un proprietario che non può effettuare l'accesso, un ruolo app per il percorso di richiesta, un ruolo report che vede solo i dati aggregati e un ruolo registro che può solo aggiungere dati (append). Nessun ruolo detiene BYPASSRLS. L'unico modo per associare un tenant è tramite una specifica funzione del database, e set_config viene revocato a tutti i ruoli tranne che al proprietario.
Un file di tenancy applicato non viene mai modificato. Una modifica costituisce una revisione con un proprio file numerato con 0, ed è in questo modo che arriva la postazione di lettura per le concessioni tra organizzazioni, come revisione 2. --graph genera le due tabelle del grafo tipizzato dichiarato da ontology come successiva migrazione numerata.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sql
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --graph --out migrations/001_graph.sqlIl file di tenancy crea gli stessi ruoli con cui si connette l'esecutore, pertanto viene applicato dal proprietario del database con nexus-migrate provision:
DATABASE_URL=<database-owner-url> npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate provision --state <dir><database-owner-url> è una stringa di connessione per il proprietario del database e <dir> è una directory privata. Il provisioning applica nell'ordine il file di tenancy di base e ogni revisione, scrive migrator.url e app.url (e seat.url una volta esistente la revisione 2) in <dir> con modalità 0600 e non stampa alcun dato segreto. Imposta il limite di connessioni di ciascun ruolo a partire da db.maxConnections × db.pods a ogni esecuzione. Una nuova esecuzione mantiene le password esistenti, a meno che non venga richiesto diversamente: --passwords <dir> le imposta da file e --rotate <roles> ne assegna di nuove ai ruoli specificati. Trasformare i file nei secret del proprio deployment.
Successivamente, l'applicazione si connette utilizzando la stringa di connessione del migratore scritta durante il provisioning:
DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.jsonEsegue i file da 001 in poi come migratore, ogni file sotto SET ROLE <schema>_owner, una transazione per file. Mantiene un registro, <schema>.schema_migrations, con il checksum di ciascun file; un file già applicato i cui byte sono cambiati viene rifiutato per nome (CHECKSUM_DRIFT), mai rieseguito e mai ignorato. Ogni file in sospeso viene analizzato con la grammatica Postgres reale prima che venga eseguito il primo, in modo che un eventuale rifiuto lasci il database intatto. L'unica intestazione che un file può contenere è -- nexus-migration: transaction=file|per-statement, con timeout opzionali per lock e istruzioni; per-statement serve per CREATE INDEX CONCURRENTLY.
I controlli
nexus-gates esegue ventidue gate. Ciascuno codifica una classe di difetti per impedire che venga rilasciata due volte, e ciascuno dispone di un autotest che ne dimostra il fallimento su una fixture appositamente costruita per farlo scattare. Eseguirli prima di effettuare il push:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test| Gate | Cosa rileva |
|---|---|
scope-adherence |
Una route /api priva della guardia di ambito; un percorso anonimo che non corrisponde esattamente a uno dichiarato; una route del dispositivo priva della guardia del dispositivo, o affiancata dalla guardia di una persona |
one-fence |
Un predicato di tenant definito in qualsiasi altro punto anziché in un unico posto, inclusa una barriera (fence) di postazione o di concessione scritta manualmente |
sql-fence |
Un'istruzione che legge o aggiorna una tabella con ambito senza la barriera (fence), in qualsiasi destinazione FROM, JOIN, USING o UPDATE |
migrations-are-scoped |
Una tabella priva di un asse, di una chiave composta che inizia con il tenant, di una chiave esterna che trasporta il tenant o della colonna demo |
migrations-commit-what-they-open |
Una migrazione il cui conteggio BEGIN non corrisponde al conteggio di COMMIT e ROLLBACK |
no-direct-compute |
Una chiamata diretta a un fornitore di modelli, motore, coda o host di workflow; un secondo lettore dell'URL di dispatch |
no-credentials |
Una credenziale di un fornitore di modelli leggibile nel repository o nell'ambiente |
crud-adherence |
Una route di modifica il cui controllo dei diritti non fa riferimento ad alcuna voce nel registro |
blocked-backends |
Una route che non è né servita, né bloccata per nome, né rifiutata per legge, né di proprietà altrui |
every-test-runs |
Test che il glob dello script di test non raggiunge mai |
tiles-are-invariant |
Un punto di giunzione (seam) memorizzato nella cache e invariante rispetto al tenant che legge un valore del tenant o salta l'autenticazione |
api-contract |
Una route registrata che il manifest non dichiara, o una route dichiarata che il codice non registra mai |
rls-present |
Una tabella senza row-level security forzata; una funzione SECURITY DEFINER senza un search_path bloccato |
no-set-config |
Codice del plugin che associa autonomamente l'impostazione del tenant |
db-role-honest |
Un percorso di richiesta che si connette come proprietario o migratore, o che richiede SUPERUSER o BYPASSRLS |
platform-clients |
Un client SDK importato ma non elencato in backend.platformClients, oppure elencato ma mai importato |
rights-register |
Una route di ambito priva di un diritto dichiarato; un controllo dei diritti al di fuori del registro |
refusal-ledger |
Una tabella dei rifiuti dichiarata senza alcun registro installato, o un corpo di rifiuto inviato aggirandolo |
grants-declared |
Una tabella concessa che il manifest non dichiara; privilegi di postazione di lettura assegnati manualmente |
people-declared |
Un blocco people privo della relativa route di sweep, della guardia e delle tabelle |
functions-closure |
Un plugin Azure Functions le cui route servite e route dichiarate non coincidono |
declared-input |
L'elenco dei parametri di query di un handler che non corrisponde a query dichiarato dalla route |
La directory gates/ contiene i cinque file di esenzione che un gate può leggere (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json e invariant-seams.json), con una motivazione per voce. Una motivazione vuota equivale a nessuna voce, e una voce che fa riferimento a qualcosa che non esiste più fa fallire il gate. È inoltre possibile inserire lì i propri moduli gate, e nexus-gates li rileverà insieme a quelli integrati.
La pipeline del modello
Il template non include alcun workflow scritto manualmente. La configurazione della pipeline indica il Dockerfile, l'unico argomento di build (il token del registro), la simulazione (dry run) di migrazione, la sonda di avvio e il gate eseguito dalla coda di merge. L'ordine corrisponde esattamente all'ordine in cui si vorrebbe che si verificasse un eventuale errore.
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest, che ècreate-nexus-plugin validate nexus.manifest.jsonnpm run gates, che ènexus-gates --self-testnode scripts/ci/required-env
Altri due controlli vengono eseguiti attorno all'immagine. La prova a secco della migrazione applica ogni file a un Postgres usa e getta prima che l'immagine possa essere rilasciata, con lo stesso runner utilizzato in produzione: nexus-migrate provision una volta come superutente, poi ciascun file numerato come migratore. Il controllo di avvio avvia l'immagine compilata con il proprio entrypoint e ogni variabile che required-env stampa, puntando a sostituti che accettano le connessioni senza mai rispondere. Il server attende il database, entro la sua finestra limitata, e tale attesa costituisce il segnale di superamento; un caricatore di configurazione che rifiuta di avviarsi fa fallire la build in quel punto e non in produzione.
Quanto costa
L'SDK prende decisioni al posto vostro, e alcune di esse le avreste prese diversamente. Il manifesto rifiuta le chiavi che non conosce, la tabella delle rotte deve corrispondere esattamente al vostro codice, i ruoli del database non spettano a voi progettarli e i gate fanno fallire una build se manca un diritto su una lettura. Sul mio primo plugin ho passato una giornata a discutere con api-contract per una rotta che avevo registrato e dimenticato di dichiarare. Aveva ragione: la rotta non era protetta. Aspettatevi che il primo plugin sembri lento, e aspettatevi che il secondo richieda un terzo del tempo.

