Versioni 1.0.0-alpha.1më i fundit
Kapitulli 2.21
Plugin SDK
Instalimi i Plugin SDK (paketa e zhvillimit të softuerit), mjetet e tij të rreshtit të komandës, një udhëtim nëpër shabllonin me shërbim të plotë, manifesti v2 fushë pas fushe dhe njëzet e dy portat që e mbajnë një shtojcë brenda rregullave.
Kjo faqe u përkthye nga AI prej origjinalit në anglisht. Nëse diçka është e paqartë, faqja në anglisht shërben si referencë. Lexoni këtë faqe në anglisht

Shtojca ime e dytë më mori një të tretën e kohës së së parës, dhe pothuajse i gjithë kursimi erdhi nga SDK-ja (kompleti i zhvillimit të softuerit). Herën e parë, shkrova një kontroll fushëveprimi, një ngarkues konfigurimi dhe një ekzekutues migrimesh, dhe një rishikues m'i ktheu mbrapsht të gjithë. Herën e dytë, ekzekutova një komandë skeleti, fshiva aftësinë shembull të analizës së ndjenjave dhe i kalova ditët me regjistrimet e rishikimit të anomalive që i nevojiteshin vërtet ekipit tonë të dinamikës së fluturimit.
@adverant-nexus/plugin-sdk është një paketë npm. Ajo përmban skemën e manifestit v2 dhe validuesit që e lexojnë atë (definePlugin, defineSkill), modulet e kohës së ekzekutimit që shtojca juaj importon për fushëveprimin, bazën e të dhënave, dërgimin dhe të tjerat, ndihmësit e testimit, portat e përputhshmërisë dhe mjetet e rreshtit të komandës. Ky kapitull trajton instalimin e saj, mjetet, shabllonin, manifestin dhe portat. Kapitulli 2.22, Koha e ekzekutimit e shtojcës, trajton modulet e kohës së ekzekutimit në kodin tuaj në ekzekutim.
Instalimi i tij
Paketa vjen nga regjistri i Adverant në https://registry.adverant.ai/npm/, kurrë nga regjistri publik npm, dhe ju nevojitet tokeni i tërheqjes nga faqja "Tokenët e tërheqjes dhe komandat e instalimit" e llogarisë suaj. Drejtojeni fushën @adverant-nexus te regjistri në .npmrc të depos suaj:
@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>
<pull-token> është tokeni nga faqja e llogarisë suaj. Në një pipeline, kalojeni nga një sekret dhe mos e bëni kurrë commit; Dockerfile i shabllonit refuzon të ndërtojë pa të dhe e fshin .npmrc nga faza e ndërtimit pasi të jetë ekzekutuar npm ci, kështu që tokeni nuk përfshihet kurrë në një imazh.
Pastaj fiksoni versionin saktësisht:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Bëni commit package-lock.json në instalimin e parë. Ndërtimi i imazhit të shabllonit ekzekuton npm ci dhe refuzon të kthehet te npm install: lockfile është kontrata. Minimumi i vetë SDK-së është Node 18; shablloni synon Node 20.
Mjetet e rreshtit të komandës vijnë brenda paketës, ndaj çdo komandë në këtë dokumentacion e emërton paketën dhe versionin e saj me npx -p. Më vete, npx create-nexus-plugin kërkohet në regjistrin publik, dhe ai emër nuk është kjo paketë.
Mjetet e rreshtit të komandës
| Mjeti | Çfarë bën |
|---|---|
create-nexus-plugin |
Krijon skeletin e një shtojce, validon një manifest, migron një manifest v1 në v2 dhe gjeneron udhëzuesin e konsumatorit për zhvilluesin tuaj të frontend-it |
nexus-tenancy |
Gjeneron SQL-në e qiramarrjes së skemës suaj nga manifesti: rolet, të drejtat, shabllonin e sigurisë në nivel rreshti dhe tabelat e grafit |
nexus-migrate |
Zbaton migrimet tuaja: krijon rolet një herë, pastaj ekzekuton çdo skedar të numëruar si roli migrues |
nexus-gates |
Ekzekuton çdo portë përputhshmërie dhe vetëtestin e secilës portë |
create-nexus-plugin nuk bën asnjë thirrje rrjeti dhe nuk ngarkon kod në distancë. Ai ekzekuton të njëjtët validues brenda procesit që ekzekuton procesi i pranimit të platformës, kështu që nuk ka mospërputhje midis "u validua në makinën time" dhe "platforma e pranoi".
| Komanda | Flamujt | Çfarë bën | Kodet e daljes |
|---|---|---|---|
scaffold <name> |
--tier full-service\|ui-only\|skills-only, --dir <path>, --print |
Shkruan një direktori të re shtojce; --print printon vetëm manifestin |
0 u shkrua · 1 refuzoi të mbishkruajë · 2 përdorim i gabuar |
validate <file> |
Validon një nexus.manifest.json, ose një modul .ts ose .js që eksporton një të tillë |
0 i vlefshëm · 1 i pavlefshëm ose i palexueshëm · 2 përdorim i gabuar | |
migrate <file> |
--write |
Ngre një manifest v1 në v2 dhe e printon, ose e shkruan në vend | 0 · 1 · 2, si më sipër |
guide |
--manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint |
Gjeneron udhëzuesin e konsumatorit nga manifesti dhe përshkrimi juaj; --check e krahason me kopjen e bërë commit dhe nuk shkruan asgjë |
0 · 1 mospërputhje ose shkelje lint · 2 përdorim i gabuar |
help |
Printon mënyrën e përdorimit | 0 |
Strukturimi fillestar dhe tri nivelet
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-service--tier ka si parazgjedhje full-service. Krijuesi i skeletit refuzon të shkruajë në një direktori që ekziston, dhe manifesti që shkruan e kalon tashmë validimin; ai nuk prodhon kurrë një manifest të pavlefshëm.
Zgjidhni nivelin sipas asaj që ka shtojca juaj.
| Niveli | Ka | Duhet të deklarojë |
|---|---|---|
skills-only |
Aftësi manifesti dhe asgjë tjetër | skills[], me të paktën një hyrje |
ui-only |
Një sipërfaqe frontend brenda shell-it | frontend |
full-service |
Një backend dhe një frontend, zakonisht me skemën e vet | backend dhe frontend; dhe meqë ka backend, runtime.healthCheck |
Nëse nuk jeni të sigurt, krijoni skeletin full-service dhe fshini atë që nuk ju nevojitet. Rruga e kundërt do të thotë të shkruani pjesët që shablloni do t'ju kishte dhënë.
Një udhëtim nëpër shabllonin me shërbim të plotë
Shablloni është shtojca referencë, e ndërtuar sipas modelit strikt që supozon çdo kapitull i mëvonshëm. Kopjoni formën e tij, jo logjikën e tij shembull.
| Shtegu | Çfarë është |
|---|---|
nexus.manifest.json |
Manifesti v2: tri ligjet të rideklaruara, tabela e rrugëve dhe regjistri i saj i të drejtave |
src/config.ts |
Ngarkuesi i konfigurimit. Një specifikim, i lexuar një herë, çdo problem i mbledhur përpara se procesi të refuzojë të niset |
src/scope.ts |
Skedari i vetëm që e kthen një kërkesë në një fushëveprim, me verifikuesin strikt të tokenëve të SDK-së dhe dy regjime: tokeni bearer i një personi dhe thirrja e shërbimit të platformës |
src/db.ts |
Çdo deklaratë kompozon tenantFence() dhe ekzekutohet brenda withScopedTx |
src/uno.ts |
Skedari i vetëm i dërgimit: një URL, një klient, një listë e mbyllur lejimesh |
src/routes/*.ts |
health (anonime, shteg i saktë), rrugët /api (me fushëveprim) dhe callback-u /internal (i mbrojtur nga shërbimi) |
src/skills/sentiment.ts |
Një aftësi deterministe host_callback; zëvendësojeni leksikun me logjikën tuaj |
src/server.ts |
Rrënja e kompozimit: instalon regjistrin e refuzimeve një herë, pret bazën e të dhënave (me kufi), pastaj ekzekuton kontrollet e izolimit dhe të regjistrit përpara se të fillojë të dëgjojë |
migrations/000_tenancy.sql |
Gjeneruar nga nexus-tenancy render në kohën e krijimit të skeletit: rolet, skema, shablloni i sigurisë në nivel rreshti |
migrations/001_init.sql |
Dy tabela me një çelës të përbërë që fillon me qiramarrësin dhe një çelës të jashtëm të përbërë që mbart qiramarrësin |
migrations/002_refusal_ledger.sql |
Tabela ku shkruan regjistri i refuzimeve |
scripts/ci/required-env |
Printon si JSON emrat e variablave të mjedisit të kërkuara për nisjen |
scripts/ci/shadow-migrate-*.sh |
Ekzekutimi provë i migrimit në pipeline, përmes nexus-migrate |
gates/ |
Direktoria e përjashtimeve të portave: bosh, që është gjendja e saktë për një shtojcë të re |
test/ |
Teste për fushëveprimin, rrugët, bazën e të dhënave, dërgimin dhe nisjen, me zëvendësuesit e fushëveprimit që injekton çdo test |
Dockerfile |
Një imazh pa root (ID e përdoruesit 10001) me migrimet brenda tij |
Disa nga këto skedarë meritojnë një vështrim më të afërt.
src/config.ts ndjek dy rregulla. Ai mbledh çdo problem përpara se të hedhë gabim, kështu që një rinisje i emërton të pesë variablat që mungojnë në vend të pesë rinisjeve që emërtojnë nga një. Dhe i jep një vlere parazgjedhje vetëm kur një vlerë e gabuar nuk mund të prodhojë një përgjigje të gabuar në heshtje: PORT mund të ketë si parazgjedhje 8080, sepse një port i gabuar e dështon lidhjen dukshëm, ndërsa DATABASE_URL dhe UNO_DISPATCH_URL janë të detyrueshme dhe duhet të jenë adresa brenda klasterit. Një adresë publike refuzohet në nisje.
node scripts/ci/required-env["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]
Testi i vetë shabllonit e ekzekuton atë skedar dhe e krahason rezultatin e tij me emrat që specifikimi i konfigurimit i shënon si të detyrueshëm, kështu që shtimi i një variabli të detyrueshëm pa përditësuar listën bën që npm test të dështojë.
src/server.ts nuk fillon të dëgjojë derisa të përgjigjet baza e të dhënave, dhe e kufizon pritjen në 120 sekonda, duke regjistruar çdo përpjekje të dështuar me shkakun e saj. Pastaj provon, me radhë, se roli i aplikacionit nuk mund ta rilidhë qiramarrësin dhe se çdo tabelë është e detyruar nën sigurinë në nivel rreshti, se grupi i lidhjeve i çdo pod-i përshtatet me kufirin e lidhjeve të rolit, dhe se tabela e regjistrit të refuzimeve mund të pranojë një rresht. Një refuzim nga cilido prej të treve printohet i plotë dhe procesi del me 2.
Manifesti v2, fushë pas fushe
Manifesti është kontrata e shtojcës, e lexueshme nga makina, me platformën. Ai validohet kur e hartoni, kur platforma e pranon dhe vazhdimisht pas kësaj. Skema është additionalProperties: false në çdo nivel: nëse shtojca juaj ka një seksion, ekziston një veti për të, dhe një çelës i padeklaruar refuzohet. Zgjidhja është gjithmonë të përdorni vetinë opsionale të duhur.
Thelbi i detyrueshëm
| Fusha | Rregulli |
|---|---|
manifestVersion |
Saktësisht "2". Një dokument v1 migrohet, nuk rivalidohet kurrë në vend |
name |
^[a-z0-9]+([-.][a-z0-9]+)*$, jo më shumë se 64 karaktere. ID-ja e shtojcës që përdoret në regjistrim, në hapësirat e emrave të dërgimit dhe në rreshtat me fushëveprim qiramarrësi. Një shtojcë që deklaron aftësi ka nevojë gjithashtu për një emër pa pikë dhe pa shifër në fillim |
displayName |
1 deri në 120 karaktere |
version |
Version semantik; cikli juaj i publikimeve |
description, author, license |
Të paktën një karakter secila |
tier |
skills-only, ui-only ose full-service |
trust |
core, verified, community ose untrusted |
runtime |
Të detyrueshme: executionMode, isolationLevel (1 deri në 4), entrypoint. Opsionale: nodeVersion, healthCheck, readinessCheck, livenessCheck, secila një shteg që fillon me /. Mënyra rrjedh nga niveli: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker |
architecture |
compute, ai dhe deploy, tri ligjet e platformës të rideklaruara. Validuesi e fikson formulimin |
Për një shtojcë që ndërtoni për instalimin tuaj, tri fjalitë lexohen si më poshtë. Fjalia ai mbulon inteligjencën artificiale (AI) dhe është vendi ku thuhet se shtojca nuk mban kredenciale modelesh.
"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."
}Tabela e rrugëve: api dhe rights
api ka nevojë për version dhe basePath, dhe opsionalisht për websocket (path, auth) dhe endpoints[]. Tabela e rrugëve është ideja më e fortë në skemë: një portë e krahason atë me rrugët që kodi juaj regjistron realisht, në të dy drejtimet, kështu që manifesti është një kontratë e verifikueshme dhe jo dokumentacion.
Çdo pikë fundore ka nevojë për method (GET, POST, PUT, PATCH ose DELETE) dhe path. Pjesa tjetër:
| Fusha | Çfarë thotë ai |
|---|---|
auth |
Një nga pesë klasat: scope (rruga e një personi, pas mbrojtësit të fushëveprimit), service-key dhe internal (server me server, kurrë të arritshme nga një shfletues), public (vetëm një shteg i saktë me allowAnonymous), dhe device (një makinë me kredencialin e vet, pas mbrojtësit të pajisjes) |
right |
E detyrueshme në çdo rrugë që shërben mbrojtësi i fushëveprimit dhe e refuzuar në çdo tjetër: emri i një të drejte në regjistrin rights |
needsUnit |
Rruga refuzon kur njësia e thirrësit nuk mund të përcaktohet |
allowAnonymous |
Vetëm listë lejimesh me përputhje të saktë. Një rregull prefiksi është mënyra si /health-of-tenant-42 përfundon publik |
group, serves, screens |
Nën një bllok release: grupi i aftësive që shërben rruga, çfarë përgjigjet ajo kur veçoria e licencuar e atij grupi është e kyçur (data, teaser, sighting ose ask), dhe ekranet që shërben |
query |
required (secili emër me një vlerë shembull) dhe allowed: parametrat e kërkesës që lexon rruga |
body |
example: trupi shembull i një rruge shkrimi, të cilin e pranon validuesi i saj. Kurrë në një GET |
rights është regjistri që emërtojnë ato rrugë. Çdo e drejtë ka roles (tavanin) dhe opsionalisht summary, never (role që nuk mund ta ushtrojnë kurrë, çfarëdo tjetër që mbajnë), barred (fjalët e vetë produktit për refuzimin e një roli never), seat (nevojitet gjithashtu një vend aktiv), self (çdo person i verifikuar e mban, për të drejtat mbi sesionin e vet), grants (mbajtësit japin vende; më së shumti një e drejtë e thotë këtë), licence (një veçori e licencuar që duhet ta përmbajë licenca e organizatës) installation (mbahet vetëm nga administratorët e vetë instalimit) dhe platform (mbahet vetëm nga administratorët e platformës së Adverant; nuk emërton role). Emrat e të drejtave kanë të paktën një pikë: 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 refuzon një rrugë fushëveprimi pa të drejtë (ENDPOINT_RIGHT_MISSING), një të drejtë që regjistrit i mungon (ENDPOINT_RIGHT_NOT_REGISTERED) dhe një të drejtë në një rrugë që nuk e shërben asnjë mbrojtës (ENDPOINT_RIGHT_UNGUARDED). Ai refuzon gjithashtu një regjistër që kundërshton veten, dhe dy shkrime të së njëjtës rrugë (:id dhe :recordId) si DUPLICATE_ENDPOINT.
Të dhënat tuaja: databases, schema dhe db
schema është skema e vetme Postgres që zotëron shtojca. public, plugins, auth dhe nexus janë të ndaluara, dhe nëse databases[] emërton gjithashtu një skemë Postgres, të dyja duhet të përputhen.
databases[] deklaron çdo depo sipas motorit: postgresql (schema, tables, migrations dhe granted, tabelat që një organizatë tjetër mund t'i lexojë nën një leje të regjistruar), neo4j (schemas), qdrant (collections) ose redis (purpose).
db mban kufijtë e sesionit për çdo lidhje që hap shtojca, të deklaruar këtu dhe jo të koduar, që t'i lexojnë si një rishikues ashtu edhe vendosja:
| Fusha | Çfarë kufizon |
|---|---|
maxConnections |
Grupi i lidhjeve për çdo replikë |
pods |
Numri maksimal i pod-eve që mbajnë një grup lidhjesh njëkohësisht, replikat plus tejkalimi i një përditësimi gradual. Kufiri i lidhjeve i çdo roli gjenerohet si maxConnections × pods; nëse e lini jashtë, definePlugin paralajmëron DB_PODS_UNDECLARED |
statementTimeoutMs |
Një deklaratë |
idleInTransactionTimeoutMs |
Një transaksion i hapur që nuk po ekzekuton asgjë |
workMemKB |
Një nyje renditjeje ose hash-i, për nyje, jo për kërkesë |
piiMask[] |
Hyrje table.column që mbajnë të dhëna personale, të maskuara në konsolën e qeverisur SQL dhe në regjistrat |
Aftësitë dhe mjetet: skills, mcpTools, entitlements
skills[] mban aftësitë e manifestit; kapitulli 2.20, Aftësitë, trajton fushat dhe nivelet e tyre. mcpTools[] mban mjetet MCP (Model Context Protocol) që publikon shtojca, secili me një name, një description dhe një inputSchema pa oneOf, allOf ose anyOf në nivelin e sipërm.
entitlements kërkon featureIdPattern dhe pranon alwaysOn[], source dhe store. Modeli emërton hapësirën e emrave ku jetojnë ID-të e veçorive tuaja, sipas konventës name e shtojcës plus një segment që kodi juaj e plotëson për çdo sipërfaqe. alwaysOn[] është lista e shkurtër dhe e saktë që duhet të përgjigjet edhe kur nuk mund të merret asnjë vendim për të drejtën e përdorimit: shëndeti, gatishmëria, hyrja dhe cilësimet që i nevojiten një administratori për të riparuar të drejtën e përdorimit.
Kontrolli i ndryshimeve: changePolicy
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Miratimet numërohen në persona të ndryshëm, dhe personi që propozoi ndryshimin nuk është kurrë një prej tyre; pa të dyja gjysmat, "dy miratime" bëhen një person që klikon dy herë. enabled: true kërkon classes, dhe çdo klasë e emërtuar ka nevojë për numrin e vet. Një klasë që e lini jashtë është e paqeverisur, që është një zgjedhje legjitime që skema ju detyron ta shkruani.
Kush jeni: domains, branding, routing
domains[] (secili primary dhe aliases[]; domain është forma me një domen të vetëm) rendit ku përgjigjet shtojca. branding kërkon appName dhe pranon tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId dhe gaId. Gjithçka në branding është publike: faqja e hyrjes e lexon përpara se dikush të ketë një kredencial, ndaj nuk mban kurrë një sekret ose një adresë të brendshme. routing (type, gateway, virtualService) është për shtojcat që përshkruajnë vetë drejtimin e tyre.
Përmasimi dhe të tjerat
resources kërkon cpuMillicores (10 deri në 64,000) dhe memoryMB (16 deri në 262,144), dhe pranon diskGB, timeoutMs, port dhe wsPort. backend përmban port, healthPath, apiPrefix, framework dhe platformClients[], klientët SDK që backend-i juaj importon me emër. Lista është e mbyllur dhe një portë e kontrollon atë kundrejt importeve tuaja. Skema lejon katërmbëdhjetë emra: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin dhe uno, plus një për klientin që u përgjigjet refuzimeve të të drejtave të planit, i cili ruan një emër të brendshëm. Klienti i të drejtave të veçorive, runtime/entitlements, nuk është një prej tyre dhe nuk shtohet kurrë në listë, sepse blloku juaj entitlements e deklaron tashmë, dhe një backend që e importon pa bllok entitlements dështon në të njëjtën portë. frontend përmban basePath, mountPath dhe framework. nexus përmban minVersion, maxVersion, capabilities[] dhe permissions[].
Blloqet e mbetura ekzistojnë secili për një detyrë të vetme:
| Blloku | Për |
|---|---|
settings |
Cilësimet tuaja në kornizën e përbashkët: groups dhe keys, të vendosura në nivelet që emërton secili |
people |
sweep (service, port): anëtarët e organizatës, të sinkronizuar nga shërbimi i identitetit, me vende pune që çaktivizohen kur dikush largohet |
ontology |
entityTypes dhe relationshipTypes: grafi i tipizuar i mbajtur në skemën tuaj |
release |
groups dhe frame: grupet e aftësive në të cilat vendosen rrugët tuaja, të lëshuara fillimisht si canary |
cells[] |
Një plugin që përbëhet nga disa njësi të shpërndashme: name, kind, entrypoint, port, wsPort për secilën |
pricing |
model, currency, tiers[] për listimin tuaj në katalog |
marketplace |
category, icon, screenshots, documentation, featured |
compliance |
instruments[], dataResidency, sovereignty |
developer, repository, keywords |
Kush e publikon dhe ku ndodhet kodi i tij |
metrics, atlas |
Dy objektet qëllimisht të hapura, për emrat tuaj të metrikave dhe për gjenerimin e dokumentacionit të arkitekturës |
Çfarë nuk mund të shprehë skema
JSON Schema përcakton formën; definePlugin shton rregullat që një skemë nuk mund t'i shprehë. classification e një aftësie nuk mund ta tejkalojë tavanin e besimit. Vetëm plugin-et core dhe verified mund të deklarojnë aftësi tool_using dhe llm_only. Çdo shteg i deklaruar duhet të jetë relativ dhe me të njëjtën origjinë, pa skemë, pa // dhe pa vijë të pjerrët mbrapsht, sepse analizuesi i URL-ve e kthen \ në / dhe /\evil.example/x zgjidhet në një origjinë tjetër. Çdo rregull që sinkronizimi i regjistrit zbaton mbi një aftësi zbatohet fillimisht këtu, me kodin e vetë sinkronizimit, kështu që validate dhe sinkronizimi e emërtojnë një rregull të shkelur në të njëjtën mënyrë.
Vleftësimi dhe kalimi nga 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
Një dështim shfaq shtegun e saktë dhe, për një rregull sinkronizimi, fillimisht kodin. Bëjeni atë një commit hook.
Një manifest v1 përditësohet në mënyrë mekanike. migrate shton tri fjalitë e ligjit, e zhvendos domain te domains[] dhe refuzon të shpikë një entrypoint që nuk e keni pasur. Ai e vlerëson rezultatin para se të shfaqë ose të shkruajë diçka, kështu që një migrim nuk e zhvendos kurrë një dështim nga mjeti në depon tuaj.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --writeLexojeni diff-in para se ta bëni commit. Fjalitë e ligjit që shton janë formulimi që fikson validuesi; për instalimin tuaj, vendosni deploy në fjalinë e treguar më sipër.
Gjenerimi i qiramarrjes dhe sigurimi i roleve
Ju nuk i shkruani kurrë me dorë dhënien e roleve ose shabllonin e sigurisë në nivel rreshti. nexus-tenancy render i shkruan ato nga schema dhe db të manifestit:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sqlSkedari i gjeneruar krijon pesë role për skemën, secili me atë që nuk duhet të zotërojë: një migrues që mund të bëhet vetëm pronar, një pronar që nuk mund të hyjë, një rol aplikacioni për shtegun e kërkesave, një rol raportimi që sheh vetëm agregate dhe një rol libri regjistrimi që mund vetëm të shtojë. Asnjë rol nuk zotëron BYPASSRLS. E vetmja mënyrë për të lidhur një tenant është një funksion i vetëm i bazës së të dhënave, dhe set_config u hiqet të gjitha roleve përveç pronarit.
Një skedar tenancy i zbatuar nuk modifikohet kurrë. Një ndryshim është një rishikim me skedarin e vet numër 0, dhe vendi i leximit për dhëniet ndër-organizatore vjen në këtë mënyrë, si rishikimi 2. --graph gjeneron dy tabelat e grafit të tipizuar që deklaron ontology juaj si migrimin tuaj të radhës me numër.
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.sqlSkedari tenancy krijon pikërisht rolet me të cilat lidhet ekzekutuesi, prandaj zbatohet nga pronari i bazës së të dhënave me 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> është një varg lidhjeje për pronarin e bazës së të dhënave, dhe <dir> është një direktori private. Provision zbaton skedarin bazë tenancy dhe çdo rishikim sipas radhës, shkruan migrator.url dhe app.url (dhe seat.url sapo të ekzistojë rishikimi 2) në <dir> me mode 0600, dhe nuk shfaq asgjë sekrete. Në çdo ekzekutim vendos kufirin e lidhjeve të çdo roli nga db.maxConnections × db.pods. Një riekzekutim i ruan fjalëkalimet ekzistuese, përveç nëse e kërkoni: --passwords <dir> i vendos ato nga skedarë dhe --rotate <roles> u jep roleve të emërtuara fjalëkalime të reja. Shndërrojini skedarët në sekretet e vendosjes suaj.
Pas kësaj, zbatimi lidhet me vargun e lidhjes së migruesit që shkroi provision:
DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.jsonAi ekzekuton skedarët nga 001 e tutje si migrues, çdo skedar nën SET ROLE <schema>_owner, një transaksion për skedar. Mban një libër regjistrimi, <schema>.schema_migrations, me checksum-in e çdo skedari; një skedar i zbatuar, bajtet e të cilit kanë ndryshuar, refuzohet me emër (CHECKSUM_DRIFT), nuk riekzekutohet kurrë dhe nuk anashkalohet kurrë. Çdo skedar në pritje analizohet me gramatikën e vërtetë të Postgres para se të ekzekutohet i pari, kështu që një refuzim e lë bazën e të dhënave të paprekur. Kreu i vetëm që mund të mbajë një skedar është -- nexus-migration: transaction=file|per-statement, me timeout opsionale për bllokimet dhe deklaratat; per-statement është për CREATE INDEX CONCURRENTLY.
Portat
nexus-gates ekzekuton njëzet e dy porta. Secila kodon një klasë defekti që të mos mund të dalë dy herë, dhe secila ka një vetë-test që provon se dështon mbi një fixture të ndërtuar për ta rrëzuar. Ekzekutojini para se të bëni push:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test| Porta | Çfarë kap |
|---|---|
scope-adherence |
Një rrugë /api pa mbrojtësin e fushës; një shteg anonim që nuk është saktësisht një i deklaruar; një rrugë pajisjeje pa mbrojtësin e pajisjes, ose me mbrojtësin e një personi pranë tij |
one-fence |
Një kusht tenant i përcaktuar kudo përveç një vendi të vetëm, përfshirë një gardh vendi ose dhënieje të shkruar me dorë |
sql-fence |
Një deklaratë që lexon ose përditëson një tabelë me fushë pa gardhin, në çdo objektiv FROM, JOIN, USING ose UPDATE |
migrations-are-scoped |
Një tabelë që i mungon një bosht, një çelës i përbërë që fillon me tenant-in, një çelës i jashtëm që mbart tenant-in ose kolona demo |
migrations-commit-what-they-open |
Një migrim, numri i BEGIN i të cilit nuk përputhet me numrin e COMMIT dhe ROLLBACK |
no-direct-compute |
Një thirrje e drejtpërdrejtë te një ofrues modeli, motor, radhë ose host workflow-sh; një lexues i dytë i URL-së së dërgimit |
no-credentials |
Një kredencial i ofruesit të modelit që mund të lexohet në depo ose në mjedis |
crud-adherence |
Një rrugë ndryshuese, kontrolli i së drejtës i së cilës nuk emërton asgjë në regjistër |
blocked-backends |
Një rrugë që as nuk shërbehet, as nuk bllokohet me emër, as nuk refuzohet me ligj, as nuk zotërohet gjetkë |
every-test-runs |
Teste që glob-i i skriptit të testeve nuk i arrin kurrë |
tiles-are-invariant |
Një pikë lidhjeje e ruajtur në cache, e pavarur nga tenant-i, që lexon një vlerë tenant-i ose anashkalon autentifikimin |
api-contract |
Një rrugë e regjistruar që manifesti nuk e deklaron, ose një e deklaruar që kodi nuk e regjistron kurrë |
rls-present |
Një tabelë pa siguri të detyruar në nivel rreshti; një funksion SECURITY DEFINER pa search_path të fiksuar |
no-set-config |
Kod plugin-i që e lidh vetë cilësimin e tenant-it |
db-role-honest |
Një shteg kërkese që lidhet si pronar ose migrues, ose që kërkon SUPERUSER ose BYPASSRLS |
platform-clients |
Një klient SDK i importuar, por i pa listuar në backend.platformClients, ose i listuar, por i paimportuar kurrë |
rights-register |
Një rrugë me fushë pa të drejtë të deklaruar; një kontroll i së drejtës jashtë regjistrit |
refusal-ledger |
Një tabelë refuzimesh e deklaruar pa libër regjistrimi të instaluar, ose një trup refuzimi i dërguar duke e anashkaluar atë |
grants-declared |
Një tabelë me dhënie që manifesti nuk e deklaron; privilegje të vendit të leximit të dhëna me dorë |
people-declared |
Një bllok people pa rrugën, mbrojtësin dhe tabelat e tij të pastrimit |
functions-closure |
Një plugin Azure Functions, rrugët e shërbyera dhe rrugët e deklaruara të të cilit nuk përputhen |
declared-input |
Një listë parametrash pyetjeje e një handler-i që nuk përputhet me query e deklaruar të rrugës |
Direktoria gates/ përmban pesë skedarët e përjashtimeve që mund të lexojë një portë (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json dhe invariant-seams.json), një arsye për çdo hyrje. Një arsye bosh llogaritet si mungesë hyrjeje, dhe një hyrje që emërton diçka që nuk ekziston më e bën portën të dështojë. Mund të vendosni aty edhe modulet tuaja të portave, dhe nexus-gates i merr ato krahas atyre të integruara.
Tubacioni i shabllonit
Shablloni nuk përfshin asnjë workflow të shkruar me dorë. Konfigurimi i tij i pipeline-it emërton Dockerfile-in, argumentin e vetëm të ndërtimit (token-in e regjistrit), provën e thatë të migrimit dhe sondën e nisjes, si dhe portën që ekzekuton radha e bashkimeve. Radha është ajo në të cilën do të donit të dështonit.
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest, që ështëcreate-nexus-plugin validate nexus.manifest.jsonnpm run gates, që ështënexus-gates --self-testnode scripts/ci/required-env
Dy kontrolle të tjera ekzekutohen rreth imazhit. Prova e thatë e migrimit zbaton çdo skedar në një Postgres të përkohshëm para se imazhi të mund të lëshohet, me të njëjtin ekzekutues që përdor prodhimi: nexus-migrate provision një herë si superpërdorues, pastaj çdo skedar me numër si migrues. Sonda e nisjes nis imazhin e ndërtuar me entrypoint-in e vet dhe çdo variabël që shfaq required-env, të drejtuar te zëvendësues që pranojnë lidhje dhe nuk përgjigjen kurrë. Serveri pret për bazën e të dhënave, brenda dritares së tij të kufizuar, dhe kjo pritje është sinjali i kalimit; një ngarkues konfigurimi që refuzon të niset e bën ndërtimin të dështojë aty dhe jo në prodhim.
Sa kushton
SDK-ja merr vendime në vend tuajin, dhe disa prej tyre do t'i kishit marrë ndryshe. Manifesti refuzon çelësat që nuk i njeh, tabela e rrugëve duhet të përputhet saktësisht me kodin tuaj, rolet e bazës së të dhënave nuk janë tuajat për t'i projektuar, dhe portat e bëjnë një ndërtim të dështojë për mungesën e një të drejte në një lexim. Në plugin-in tim të parë kalova një ditë duke debatuar me api-contract për një rrugë që e kisha regjistruar dhe kisha harruar ta deklaroja. Kishte të drejtë; rruga ishte e pambrojtur. Prisni që plugin-i i parë të duket i ngadaltë, dhe prisni që i dyti të marrë një të tretën e kohës.

