HyniRezervoni një prezantim

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

22 minuta lexim

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

Bë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 --write

Lexojeni 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.sql

Skedari 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.sql

Skedari 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.json

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

Përputhshmëria
Përputhshmëria
Përputhshmëria tregon cili version i SDK-së funksionon me cilin version të platformës, nga ekzekutimet e përnatshme të quickstart-it. Një çift i patestuar e thotë këtë, dhe një çift që dështon emërton ndryshimin që e prishi.

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.

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

Ndërtimi në Community
Ndërtimi në Community
Në Community, një zhvillues merr të njëjtat shtigje të arta, një hapësirë zhvillimi dhe degë të dhënash në një server të vetëm, me kodin në hostin e vet Git. Staging, njësitë pilot dhe kopjet e maskuara të të dhënave reale vijnë me Enterprise.

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.