Versiune 1.0.0-alpha.1cea mai recentă
Capitolul 2.21
Plugin SDK
Instalarea Plugin SDK (kitul de dezvoltare software), instrumentele sale în linie de comandă, o prezentare a șablonului complet de servicii, manifestul v2 câmp cu câmp și cele douăzeci și două de porți de control care obligă un plugin să respecte regulile.
Această pagină a fost tradusă cu ajutorul IA din originalul în limba engleză. Dacă există neclarități, pagina în limba engleză rămâne cea de referință. Citiți această pagină în limba engleză

Al doilea meu plugin a durat o treime din timpul primului, iar aproape toată economia s-a datorat SDK-ului (software development kit). Prima dată am scris o verificare de domeniu, un încărcător de configurație și un executor de migrări, iar un evaluator mi le-a respins pe toate. A doua oară am rulat o singură comandă de generare a scheletului, am șters skill-ul de exemplu pentru analiza sentimentului și mi-am petrecut zilele cu înregistrările de analiză a anomaliilor de care echipa noastră de dinamică a zborului avea cu adevărat nevoie.
@adverant-nexus/plugin-sdk este un singur pachet npm. Acesta conține schema manifestului v2 și validatoarele care o citesc (definePlugin, defineSkill), modulele de runtime pe care plugin-ul dumneavoastră le importă pentru domeniu, bază de date, dispecerizare și celelalte, utilitare de testare, porțile de conformitate și instrumentele din linia de comandă. Acest capitol tratează instalarea, instrumentele, șablonul, manifestul și porțile. Capitolul 2.22, Runtime-ul plugin-ului, tratează modulele de runtime din codul dumneavoastră în execuție.
Instalarea acestuia
Pachetul provine din registrul Adverant de la https://registry.adverant.ai/npm/, niciodată din registrul npm public, iar aveți nevoie de tokenul de descărcare de pe pagina „Pull tokens and install commands” a contului dumneavoastră. Direcționați domeniul @adverant-nexus către registru în fișierul .npmrc al depozitului dumneavoastră:
@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>
<pull-token> este tokenul de pe pagina contului dumneavoastră. Într-un pipeline, transmiteți-l dintr-un secret și nu îl includeți niciodată într-un commit; Dockerfile-ul șablonului refuză să construiască imaginea fără el și șterge .npmrc din etapa de construire după ce npm ci a rulat, astfel încât tokenul nu ajunge niciodată într-o imagine.
Apoi fixați versiunea exact:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Includeți package-lock.json într-un commit la prima instalare. Construirea imaginii din șablon rulează npm ci și refuză să revină la npm install: fișierul de blocare este contractul. Versiunea minimă a SDK-ului este Node 18; șablonul vizează Node 20.
Instrumentele din linia de comandă sunt livrate în pachet, astfel încât fiecare comandă din această documentație denumește pachetul și versiunea sa cu npx -p. Singur, npx create-nexus-plugin este căutat în registrul public, iar acel nume nu este acest pachet.
Instrumentele în linie de comandă
| Instrument | Ce face |
|---|---|
create-nexus-plugin |
Generează scheletul unui plugin, validează un manifest, migrează un manifest v1 la v2 și generează ghidul pentru consumatori destinat dezvoltatorului dumneavoastră de frontend |
nexus-tenancy |
Generează din manifest codul SQL de multi-tenanță al schemei dumneavoastră: roluri, permisiuni, șablonul de securitate la nivel de rând și tabelele de graf |
nexus-migrate |
Aplică migrările dumneavoastră: provizionează rolurile o singură dată, apoi rulează fiecare fișier numerotat cu rolul de migrare |
nexus-gates |
Rulează fiecare poartă de conformitate și autotestul fiecărei porți |
create-nexus-plugin nu efectuează niciun apel de rețea și nu încarcă cod de la distanță. Rulează aceleași validatoare în proces pe care le rulează procesul de integrare al platformei, deci nu există diferențe între „a fost validat pe mașina mea” și „platforma l-a acceptat”.
| Comandă | Opțiuni | Ce face | Coduri de ieșire |
|---|---|---|---|
scaffold <name> |
--tier full-service\|ui-only\|skills-only, --dir <path>, --print |
Scrie un nou director de plugin; --print afișează doar manifestul |
0 scris · 1 suprascriere refuzată · 2 utilizare incorectă |
validate <file> |
Validează un nexus.manifest.json sau un modul .ts ori .js care exportă unul |
0 valid · 1 invalid sau ilizibil · 2 utilizare incorectă | |
migrate <file> |
--write |
Ridică un manifest v1 la v2 și îl afișează sau îl scrie pe loc | 0 · 1 · 2, ca mai sus |
guide |
--manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint |
Generează ghidul pentru consumatori din manifest și din textul dumneavoastră narativ; --check compară cu copia din commit și nu scrie nimic |
0 · 1 divergență sau o abatere de lint · 2 utilizare incorectă |
help |
Afișează modul de utilizare | 0 |
Generarea structurii (scaffolding) și cele trei niveluri
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-service--tier are valoarea implicită full-service. Generatorul de schelet refuză să scrie într-un director existent, iar manifestul pe care îl scrie trece deja validarea; nu emite niciodată unul invalid.
Alegeți nivelul în funcție de ce conține plugin-ul dumneavoastră.
| Nivel | Conține | Trebuie să declare |
|---|---|---|
skills-only |
Skill-uri de manifest și nimic altceva | skills[], cu cel puțin o intrare |
ui-only |
O suprafață de frontend în interiorul shell-ului | frontend |
full-service |
Un backend și un frontend, de obicei cu propria schemă | backend și frontend; iar, deoarece are un backend, runtime.healthCheck |
Dacă nu sunteți sigur, generați scheletul full-service și ștergeți ce nu vă trebuie. Varianta inversă înseamnă să scrieți părțile pe care vi le-ar fi oferit șablonul.
O prezentare a șablonului complet de servicii
Șablonul este plugin-ul de referință, construit după modelul strict pe care îl presupune fiecare capitol ulterior. Preluați-i structura, nu logica de exemplu.
| Cale | Ce reprezintă |
|---|---|
nexus.manifest.json |
Manifestul v2: cele trei legi reformulate, tabelul de rute și registrul său de drepturi |
src/config.ts |
Încărcătorul de configurație. O singură specificație, citită o singură dată, cu toate problemele colectate înainte ca procesul să refuze pornirea |
src/scope.ts |
Singurul fișier care transformă o cerere într-un domeniu, cu verificatorul strict de tokenuri al SDK-ului și două regimuri: tokenul bearer al unei persoane și apelul de serviciu al platformei |
src/db.ts |
Fiecare instrucțiune compune tenantFence() și rulează în interiorul withScopedTx |
src/uno.ts |
Singurul fișier de dispecerizare: un URL, un client, o listă de permisiuni închisă |
src/routes/*.ts |
health (anonim, cale exactă), rutele /api (cu domeniu) și callback-ul /internal (protejat pentru servicii) |
src/skills/sentiment.ts |
Un skill host_callback determinist; înlocuiți lexiconul cu propria dumneavoastră logică |
src/server.ts |
Rădăcina de compunere: instalează registrul de refuzuri o singură dată, așteaptă baza de date (limitat în timp), apoi rulează verificările de izolare și ale registrului înainte de a asculta |
migrations/000_tenancy.sql |
Generat de nexus-tenancy render la crearea scheletului: roluri, schemă, șablonul de securitate la nivel de rând |
migrations/001_init.sql |
Două tabele cu o cheie compusă care începe cu tenantul și o cheie străină compusă care include tenantul |
migrations/002_refusal_ledger.sql |
Tabelul în care scrie registrul de refuzuri |
scripts/ci/required-env |
Afișează în format JSON numele variabilelor de mediu necesare la pornire |
scripts/ci/shadow-migrate-*.sh |
Rularea de probă a migrărilor din pipeline, prin nexus-migrate |
gates/ |
Directorul de excepții al porților: gol, aceasta fiind starea corectă pentru un plugin nou |
test/ |
Teste pentru domeniu, rute, baza de date, dispecerizare și pornire, cu dublurile de domeniu pe care le injectează fiecare test |
Dockerfile |
O imagine fără root (ID de utilizator 10001), cu migrările incluse |
Câteva dintre aceste fișiere merită o privire mai atentă.
src/config.ts respectă două reguli. Colectează toate problemele înainte de a arunca o excepție, astfel încât o singură repornire numește toate cele cinci variabile lipsă, în loc de cinci reporniri care numesc câte una. Și atribuie o valoare implicită doar atunci când o valoare greșită nu poate produce în tăcere un răspuns greșit: PORT poate avea implicit 8080, deoarece un port greșit face ca legarea să eșueze vizibil, în timp ce DATABASE_URL și UNO_DISPATCH_URL sunt obligatorii și trebuie să fie adrese din interiorul clusterului. O adresă publică este refuzată la pornire.
node scripts/ci/required-env["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]
Testul propriu al șablonului rulează acel fișier și compară rezultatul cu numele pe care specificația de configurație le marchează ca obligatorii, astfel încât adăugarea unei variabile obligatorii fără actualizarea listei face ca npm test să eșueze.
src/server.ts nu începe să asculte până când baza de date nu răspunde și limitează așteptarea la 120 de secunde, înregistrând fiecare încercare eșuată împreună cu cauza ei. Apoi demonstrează, în ordine, că rolul aplicației nu poate schimba tenantul și că fiecare tabel este supus forțat securității la nivel de rând, că pool-ul fiecărui pod se încadrează în limita de conexiuni a rolului și că tabelul registrului de refuzuri poate primi un rând. Un refuz din oricare dintre cele trei este afișat integral, iar procesul se încheie cu codul 2.
Manifestul v2, câmp cu câmp
Manifestul este contractul plugin-ului cu platforma, într-o formă care poate fi citită automat. Este validat când îl redactați, când platforma îl integrează și continuu după aceea. Schema este additionalProperties: false la fiecare nivel: dacă plugin-ul dumneavoastră are o secțiune, există o proprietate pentru ea, iar o cheie nedeclarată este refuzată. Soluția este întotdeauna utilizarea proprietății opționale corecte.
Nucleul obligatoriu
| Câmp | Regulă |
|---|---|
manifestVersion |
Exact "2". Un document v1 este migrat, niciodată revalidat pe loc |
name |
^[a-z0-9]+([-.][a-z0-9]+)*$, cel mult 64 de caractere. ID-ul plugin-ului folosit la înregistrare, la spațiile de nume pentru dispecerizare și în rândurile delimitate per tenant. Un plugin care declară skill-uri are nevoie și de un nume fără punct și care nu începe cu o cifră |
displayName |
Între 1 și 120 de caractere |
version |
Versiune semantică; propriul dumneavoastră ciclu de lansări |
description, author, license |
Cel puțin un caracter fiecare |
tier |
skills-only, ui-only sau full-service |
trust |
core, verified, community sau untrusted |
runtime |
Obligatorii: executionMode, isolationLevel (de la 1 la 4), entrypoint. Opționale: nodeVersion, healthCheck, readinessCheck, livenessCheck, fiecare fiind o cale care începe cu /. Modul este derivat din nivel: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker |
architecture |
compute, ai și deploy, cele trei legi ale platformei reformulate. Validatorul fixează formularea |
Pentru un plugin pe care îl construiți pentru propria instalare, cele trei propoziții sună după cum urmează. Propoziția ai se referă la inteligența artificială (IA) și este locul în care precizați că plugin-ul nu deține credențiale pentru modele.
"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."
}Tabelul de rute: api și rights
api necesită version și basePath și, opțional, websocket (path, auth) și endpoints[]. Tabelul de rute este cea mai puternică idee din schemă: o poartă îl compară cu rutele pe care codul dumneavoastră le înregistrează efectiv, în ambele direcții, astfel încât manifestul este un contract verificabil, nu documentație.
Fiecare endpoint necesită method (GET, POST, PUT, PATCH sau DELETE) și path. Restul:
| Câmp | Ce indică |
|---|---|
auth |
Una dintre cinci clase: scope (ruta unei persoane, în spatele gardei de domeniu), service-key și internal (de la server la server, niciodată accesibile dintr-un browser), public (întotdeauna doar o cale exactă cu allowAnonymous) și device (o mașină cu propria credențială, în spatele gardei de dispozitiv) |
right |
Obligatoriu pe fiecare rută deservită de garda de domeniu și refuzat pe oricare alta: numele unui drept din registrul rights |
needsUnit |
Ruta refuză cererea atunci când unitatea apelantului nu poate fi determinată |
allowAnonymous |
Doar listă de permisiuni cu potrivire exactă. O regulă de prefix este modul în care /health-of-tenant-42 ajunge public |
group, serves, screens |
Într-un bloc release: grupul de capabilități pe care îl deservește ruta, ce răspunde aceasta atunci când funcționalitatea licențiată a grupului este blocată (data, teaser, sighting sau ask) și ecranele pe care le deservește |
query |
required (fiecare nume cu o valoare de exemplu) și allowed: parametrii de interogare pe care îi citește ruta |
body |
example: corpul de exemplu al unei rute de scriere, unul acceptat de propriul validator. Niciodată pe un GET |
rights este registrul pe care îl numesc acele rute. Fiecare drept are roles (plafonul) și, opțional, summary, never (roluri care nu îl pot exercita niciodată, indiferent ce altceva dețin), barred (formularea proprie a produsului pentru refuzarea unui rol never), seat (este necesar și un loc activ), self (îl deține fiecare persoană verificată, pentru drepturi asupra propriei sesiuni), grants (deținătorii acordă locuri; cel mult un drept poate specifica acest lucru), licence (o funcționalitate licențiată pe care trebuie să o includă licența organizației) installation (deținut doar de administratorii instalației) și platform (deținut doar de administratorii platformei Adverant; nu numește roluri). Numele drepturilor conțin cel puțin un punct: 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 refuză o rută cu domeniu fără drept (ENDPOINT_RIGHT_MISSING), un drept care lipsește din registru (ENDPOINT_RIGHT_NOT_REGISTERED) și un drept pe o rută pe care nu o deservește nicio gardă (ENDPOINT_RIGHT_UNGUARDED). Refuză, de asemenea, un registru care se contrazice și două scrieri ale aceleiași rute (:id și :recordId) ca DUPLICATE_ENDPOINT.
Datele dumneavoastră: databases, schema și db
schema este singura schemă Postgres pe care o deține plugin-ul. public, plugins, auth și nexus sunt interzise, iar dacă databases[] numește și el o schemă Postgres, cele două trebuie să coincidă.
databases[] declară fiecare stocare după motor: postgresql (schema, tables, migrations și granted, tabelele pe care o altă organizație le poate citi în baza unei permisiuni înregistrate), neo4j (schemas), qdrant (collections) sau redis (purpose).
db conține limitele de sesiune pentru fiecare conexiune deschisă de plugin, declarate aici în loc să fie codificate, astfel încât să le poată citi atât un evaluator, cât și implementarea:
| Câmp | Ce limitează |
|---|---|
maxConnections |
Pool-ul per replică |
pods |
Numărul maxim de pod-uri care dețin simultan un pool, replici plus surplusul unei actualizări progresive. Limita de conexiuni a fiecărui rol este generată ca maxConnections × pods; dacă o omiteți, definePlugin avertizează DB_PODS_UNDECLARED |
statementTimeoutMs |
O instrucțiune |
idleInTransactionTimeoutMs |
O tranzacție deschisă care nu execută nimic |
workMemKB |
Un nod de sortare sau hash, per nod, nu per interogare |
piiMask[] |
Intrări table.column care conțin date personale, mascate în consola SQL guvernată și în jurnale |
Skill-uri și instrumente: skills, mcpTools, entitlements
skills[] conține skill-urile de manifest; capitolul 2.20, Skill-uri, tratează câmpurile și nivelurile acestora. mcpTools[] conține instrumentele MCP (Model Context Protocol) pe care le publică plugin-ul, fiecare având un name, un description și un inputSchema, fără oneOf, allOf sau anyOf la nivelul superior.
entitlements necesită featureIdPattern și acceptă alwaysOn[], source și store. Modelul numește spațiul de nume în care se află ID-urile funcționalităților dumneavoastră, prin convenție name al plugin-ului plus un segment pe care codul dumneavoastră îl completează pentru fiecare suprafață. alwaysOn[] este lista scurtă și exactă care trebuie să răspundă chiar și atunci când nu se poate obține niciun verdict privind drepturile de utilizare: starea de sănătate, disponibilitatea, autentificarea și setările de care are nevoie un administrator pentru a repara dreptul de utilizare.
Controlul modificărilor: changePolicy
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Aprobările se numără în persoane distincte, iar persoana care a propus modificarea nu este niciodată una dintre ele; fără ambele condiții, „două aprobări” devine o persoană care face clic de două ori. enabled: true necesită classes, iar fiecare clasă numită are nevoie de propriul număr. O clasă pe care o omiteți nu este guvernată, ceea ce reprezintă o alegere legitimă pe care schema vă obligă să o consemnați.
Cine sunteți: domains, branding, routing
domains[] (fiecare cu primary și aliases[]; domain este forma pentru un singur domeniu) enumeră unde răspunde plugin-ul. branding necesită appName și acceptă tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId și gaId. Tot ce se află în branding este public: pagina de autentificare îl citește înainte ca cineva să aibă o credențială, deci nu conține niciodată un secret sau o adresă internă. routing (type, gateway, virtualService) este destinat plugin-urilor care își descriu propria rutare.
Dimensionare și restul
resources necesită cpuMillicores (între 10 și 64.000) și memoryMB (între 16 și 262.144) și acceptă diskGB, timeoutMs, port și wsPort. backend conține port, healthPath, apiPrefix, framework și platformClients[], clienții SDK pe care backendul dumneavoastră îi importă după nume. Lista este închisă, iar o verificare o compară cu importurile dumneavoastră. Schema permite paisprezece nume: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin și uno, plus unul pentru clientul care răspunde la refuzurile privind drepturile din plan, care își păstrează un nume intern. Clientul pentru drepturile asupra funcționalităților, runtime/entitlements, nu este unul dintre ele și nu se trece niciodată pe listă, deoarece blocul dumneavoastră entitlements îl declară deja, iar un backend care îl importă fără un bloc entitlements eșuează la aceeași verificare. frontend conține basePath, mountPath și framework. nexus conține minVersion, maxVersion, capabilities[] și permissions[].
Blocurile rămase există fiecare pentru o singură sarcină:
| Bloc | Pentru |
|---|---|
settings |
Setările dumneavoastră din cadrul comun: groups și keys, stabilite la nivelurile pe care le numește fiecare |
people |
sweep (service, port): membrii organizației, sincronizați din serviciul de identitate, cu locurile dezactivate atunci când cineva pleacă |
ontology |
entityTypes și relationshipTypes: graful tipizat păstrat în propria dumneavoastră schemă |
release |
groups și frame: grupurile de capabilități în care sunt etapizate rutele dumneavoastră, lansate mai întâi ca canary |
cells[] |
Un plugin format din mai multe componente implementabile: name, kind, entrypoint, port, wsPort pentru fiecare |
pricing |
model, currency, tiers[] pentru listarea dumneavoastră în catalog |
marketplace |
category, icon, screenshots, documentation, featured |
compliance |
instruments[], dataResidency, sovereignty |
developer, repository, keywords |
Cine îl publică și unde se află codul său |
metrics, atlas |
Cele două obiecte lăsate intenționat deschise, pentru propriile dumneavoastră nume de metrici și pentru generarea documentației de arhitectură |
Ce nu poate exprima schema
JSON Schema stabilește forma; definePlugin adaugă regulile pe care o schemă nu le poate exprima. classification al unei abilități nu poate depăși plafonul de încredere. Doar pluginurile core și verified pot declara abilități tool_using și llm_only. Fiecare cale declarată trebuie să fie relativă și de aceeași origine, fără schemă, fără // și fără backslash, deoarece parserul de URL transformă \ în /, iar /\evil.example/x se rezolvă către altă origine. Fiecare regulă pe care sincronizarea registrului o aplică unei abilități este aplicată mai întâi aici, cu propriul cod al sincronizării, astfel încât validate și sincronizarea denumesc o regulă încălcată în același fel.
Validarea și trecerea de la 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 eșec afișează calea exactă și, pentru o regulă de sincronizare, mai întâi codul. Transformați-l într-un hook de commit.
Un manifest v1 se migrează mecanic. migrate adaugă cele trei propoziții de lege, mută domain în domains[] și refuză să inventeze un punct de intrare pe care nu îl aveați. Validează rezultatul înainte de a afișa sau de a scrie ceva, astfel încât o migrare nu mută niciodată un eșec din instrument în depozitul dumneavoastră.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --writeCitiți diferențele înainte de a le face commit. Propozițiile de lege pe care le adaugă sunt formularea fixată de validator; pentru propria dumneavoastră instalare, setați deploy la propoziția prezentată anterior.
Randarea structurii multi-tenant și provizionarea rolurilor
Nu scrieți niciodată manual acordările de roluri sau șablonul de securitate la nivel de rând. nexus-tenancy render le scrie pe baza schema și db din manifest:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sqlFișierul generat creează cinci roluri pentru schemă, fiecare cu ceea ce nu trebuie să dețină: un migrator care poate doar să devină proprietar, un proprietar care nu se poate autentifica, un rol de aplicație pentru calea cererilor, un rol de raportare care vede doar agregate și un rol de registru care poate doar să adauge. Niciun rol nu deține BYPASSRLS. Singura modalitate de a lega un tenant este o funcție de bază de date, iar set_config este revocat de la toate rolurile, cu excepția proprietarului.
Un fișier de tenancy aplicat nu se editează niciodată. O modificare este o revizie cu propriul fișier numărul 0, iar locul de citire pentru acordările între organizații sosește astfel, ca revizia 2. --graph generează cele două tabele ale grafului tipizat declarat de ontology ca următoarea dumneavoastră migrare numerotată.
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.sqlFișierul de tenancy creează chiar rolurile cu care se conectează executorul, așa că este aplicat de proprietarul bazei de date cu 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> este un șir de conexiune pentru proprietarul bazei de date, iar <dir> este un director privat. Provizionarea aplică fișierul de tenancy de bază și fiecare revizie în ordine, scrie migrator.url și app.url (și seat.url odată ce există revizia 2) în <dir> cu modul 0600 și nu afișează nimic secret. La fiecare rulare, setează limita de conexiuni a fiecărui rol din db.maxConnections × db.pods. O rulare repetată păstrează parolele existente, cu excepția cazului în care cereți altfel: --passwords <dir> le setează din fișiere, iar --rotate <roles> le dă rolurilor numite parole noi. Transformați fișierele în secretele implementării dumneavoastră.
După aceea, aplicarea se conectează cu șirul de conexiune al migratorului pe care l-a scris provizionarea:
DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.jsonRulează fișierele de la 001 înainte ca migrator, fiecare fișier sub SET ROLE <schema>_owner, câte o tranzacție pe fișier. Păstrează un registru, <schema>.schema_migrations, cu suma de control a fiecărui fișier; un fișier aplicat ai cărui octeți s-au modificat este refuzat nominal (CHECKSUM_DRIFT), nu este niciodată rulat din nou și nu este niciodată omis. Fiecare fișier în așteptare este analizat cu gramatica reală Postgres înainte ca primul să ruleze, astfel încât un refuz lasă baza de date neatinsă. Singurul antet pe care îl poate avea un fișier este -- nexus-migration: transaction=file|per-statement, cu timeout-uri opționale pentru blocări și instrucțiuni; per-statement este pentru CREATE INDEX CONCURRENTLY.
Porțile de control
nexus-gates rulează douăzeci și două de verificări. Fiecare codifică o clasă de defecte, astfel încât aceasta să nu poată fi livrată de două ori, și fiecare are un autotest care dovedește că eșuează pe un fixture construit pentru a o declanșa. Rulați-le înainte de push:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test| Verificare | Ce detectează |
|---|---|
scope-adherence |
O rută /api fără protecția de scope; o cale anonimă care nu este exact una declarată; o rută de dispozitiv fără protecția de dispozitiv sau cu protecția pentru persoane alături de ea |
one-fence |
Un predicat de tenant definit oriunde altundeva decât într-un singur loc, inclusiv o barieră de loc sau de acordare scrisă manual |
sql-fence |
O instrucțiune care citește sau actualizează un tabel cu scope fără barieră, în orice țintă FROM, JOIN, USING sau UPDATE |
migrations-are-scoped |
Un tabel căruia îi lipsește o axă, o cheie compusă care începe cu tenantul, o cheie externă care poartă tenantul sau coloana demo |
migrations-commit-what-they-open |
O migrare al cărei număr de BEGIN nu corespunde cu numărul de COMMIT și ROLLBACK |
no-direct-compute |
Un apel direct către un furnizor de modele, un motor, o coadă sau o gazdă de fluxuri de lucru; un al doilea cititor al URL-ului de dispecerizare |
no-credentials |
O credențială a unui furnizor de modele care poate fi citită în depozit sau în mediu |
crud-adherence |
O rută de modificare a cărei verificare a dreptului nu numește nimic din registru |
blocked-backends |
O rută care nu este nici servită, nici blocată nominal, nici refuzată prin lege, nici deținută în altă parte |
every-test-runs |
Teste la care glob-ul scriptului de testare nu ajunge niciodată |
tiles-are-invariant |
O interfață în cache invariantă față de tenant care citește o valoare de tenant sau omite autentificarea |
api-contract |
O rută înregistrată pe care manifestul nu o declară sau una declarată pe care codul nu o înregistrează niciodată |
rls-present |
Un tabel fără securitate la nivel de rând forțată; o funcție SECURITY DEFINER fără un search_path fixat |
no-set-config |
Cod de plugin care setează singur parametrul de tenant |
db-role-honest |
O cale de cereri care se conectează ca proprietar sau migrator ori care solicită SUPERUSER sau BYPASSRLS |
platform-clients |
Un client SDK importat, dar nelistat în backend.platformClients, sau listat, dar niciodată importat |
rights-register |
O rută cu scope fără un drept declarat; o verificare a dreptului în afara registrului |
refusal-ledger |
Un tabel de refuzuri declarat fără registru instalat sau un corp de refuz trimis ocolindu-l |
grants-declared |
Un tabel acordat pe care manifestul nu îl declară; privilegii de loc de citire acordate manual |
people-declared |
Un bloc people fără ruta, protecția și tabelele sale de curățare |
functions-closure |
Un plugin Azure Functions ale cărui rute servite și rute declarate nu coincid |
declared-input |
O listă de parametri de interogare a unui handler care nu corespunde cu query declarat al rutei |
Directorul gates/ conține cele cinci fișiere de excepții pe care le poate citi o verificare (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json și invariant-seams.json), cu câte un motiv pentru fiecare intrare. Un motiv gol înseamnă că intrarea nu există, iar o intrare care numește ceva ce nu mai există face verificarea să eșueze. De asemenea, puteți plasa acolo propriile module de verificare, iar nexus-gates le preia alături de cele încorporate.
Fluxul de execuție (pipeline) al șablonului
Șablonul nu include niciun flux de lucru scris manual. Configurația sa de pipeline numește Dockerfile-ul, singurul argument de build (tokenul registrului), rularea de probă a migrării și testul de pornire, precum și verificarea pe care o rulează coada de merge. Ordinea este cea în care ați dori să apară eșecurile.
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest, care estecreate-nexus-plugin validate nexus.manifest.jsonnpm run gates, care estenexus-gates --self-testnode scripts/ci/required-env
Alte două verificări rulează în jurul imaginii. Rularea de probă a migrării aplică fiecare fișier pe un Postgres temporar înainte ca imaginea să poată fi lansată, cu același executor folosit în producție: nexus-migrate provision o dată ca superutilizator, apoi fiecare fișier numerotat ca migrator. Testul de pornire pornește imaginea construită cu propriul punct de intrare și cu fiecare variabilă afișată de required-env, îndreptate către înlocuitori care acceptă conexiuni și nu răspund niciodată. Serverul așteaptă baza de date, în intervalul său limitat, iar această așteptare este semnalul de reușită; un încărcător de configurație care refuză să pornească face ca build-ul să eșueze acolo, și nu în producție.
Cât costă
SDK-ul ia decizii în locul dumneavoastră, iar pe unele dintre ele le-ați fi luat altfel. Manifestul refuză cheile pe care nu le cunoaște, tabelul de rute trebuie să corespundă exact codului dumneavoastră, rolurile bazei de date nu sunt ale dumneavoastră de proiectat, iar verificările fac un build să eșueze din cauza unui drept lipsă la o citire. La primul meu plugin am petrecut o zi certându-mă cu api-contract din cauza unei rute pe care o înregistrasem și uitasem să o declar. Avea dreptate; ruta nu era protejată. Așteptați-vă ca primul plugin să pară lent și ca al doilea să dureze o treime din timp.

