AutentificareProgramați o prezentare

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ă

22 minute de lectură

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.0

Includeț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 --write

Citiț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.sql

Fiș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.sql

Fiș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.json

Rulează 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.

Compatibilitate
Compatibilitate
Compatibilitatea arată ce versiune de SDK funcționează cu ce versiune de platformă, pe baza rulărilor nocturne ale ghidului de pornire rapidă. O pereche netestată este marcată ca atare, iar o pereche care eșuează numește modificarea care a stricat-o.

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.

  1. npm ci
  2. npm run typecheck
  3. npm run build
  4. npm test
  5. npm run validate:manifest, care este create-nexus-plugin validate nexus.manifest.json
  6. npm run gates, care este nexus-gates --self-test
  7. node 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.

Construirea pe Community
Construirea pe Community
Pe Community, un dezvoltator beneficiază de aceleași căi standard, de un spațiu de dezvoltare și de ramuri de date pe un singur server, cu codul în propria gazdă Git. Mediul de staging, unitățile pilot și copiile mascate ale datelor reale sunt disponibile cu Enterprise.

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.