PieteiktiesPieteikt konsultāciju

2.21. nodaļa

Spraudņu SDK

Spraudņu SDK (programmatūras izstrādes komplekta) instalēšana, tā komandrindas rīki, pilna servisa veidnes apskats, v2 manifesta lauku apraksts un divdesmit divas kontroles barjeras, kas nodrošina spraudņa atbilstību noteikumiem.

Šo lapu no oriģināla angļu valodā ir tulkojis MI. Neskaidrību gadījumā par pamatu jāņem lapa angļu valodā. Lasīt šo lapu angļu valodā

22 minūšu lasīšana

Mana otrā spraudņa izstrāde aizņēma trešdaļu no pirmā spraudņa laika, un gandrīz visu ietaupījumu nodrošināja SDK (programmatūras izstrādes komplekts). Pirmajā reizē es uzrakstīju tvēruma pārbaudi, konfigurācijas ielādētāju un migrācijas izpildītāju, un recenzents katru no tiem nosūtīja atpakaļ. Otrajā reizē es izpildīju vienu karkasa izveides komandu, izdzēsu parauga noskaņojuma prasmi un veltīju savas dienas anomāliju pārskata ierakstiem, kas mūsu lidojumu dinamikas komandai patiešām bija nepieciešami.

@adverant-nexus/plugin-sdk ir viena npm pakotne. Tajā ir v2 manifesta shēma un validatori, kas to lasa (definePlugin, defineSkill), izpildlaika moduļi, ko jūsu spraudnis importē tvērumam, datubāzei, nosūtīšanai un pārējam, testēšanas palīgrīki, atbilstības vārti un komandrindas rīki. Šajā nodaļā ir apskatīta tās instalēšana, rīki, veidne, manifests un vārti. 2.22. nodaļā, Spraudņa izpildlaiks, ir apskatīti izpildlaika moduļi jūsu darbojošajā kodā.

Instalēšana

Pakotne nāk no Adverant reģistra vietnē https://registry.adverant.ai/npm/, nekad no publiskā npm reģistra, un jums ir nepieciešama izgūšanas pilnvara no jūsu konta lapas "Pull tokens and install commands". Norādiet @adverant-nexus tvērumu uz reģistru savas krātuves failā .npmrc:

@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>

<pull-token> ir pilnvara no jūsu konta lapas. Konveijerā padodiet to no noslēpuma un nekad neapstipriniet krātuvē; veidnes Dockerfile atsakās būvēt bez tās un izdzēš .npmrc no būvēšanas posma, tiklīdz npm ci ir izpildīts, tādēļ pilnvara nekad nenonāk attēlā.

Pēc tam precīzi piesaistiet versiju:

npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0

Apstipriniet package-lock.json pirmajā instalēšanas reizē. Veidnes attēla būvēšana izpilda npm ci un atsakās atkāpties uz npm install: bloķēšanas fails ir līgums. Paša SDK minimālā prasība ir Node 18; veidnes mērķis ir Node 20.

Komandrindas rīki tiek piegādāti pakotnes iekšienē, tāpēc katra komanda šajā dokumentācijā nosauc pakotni un tās versiju ar npx -p. Atsevišķi npx create-nexus-plugin tiek meklēts publiskajā reģistrā, un šis nosaukums nav šī pakotne.

Komandrindas rīki

Rīks Ko tas dara
create-nexus-plugin Izveido spraudņa karkasu, validē manifestu, migrē v1 manifestu uz v2 un atveido patērētāja ceļvedi jūsu priekšgala izstrādātājam
nexus-tenancy No manifesta atveido jūsu shēmas nomnieku izolācijas SQL: lomas, piešķīrumus, rindu līmeņa drošības veidni un grafa tabulas
nexus-migrate Lieto jūsu migrācijas: vienreiz nodrošina lomas, pēc tam izpilda katru numurēto failu kā migratora loma
nexus-gates Izpilda katrus atbilstības vārtus un katru vārtu paštestu

create-nexus-plugin neveic tīkla izsaukumus un neielādē attālinātu kodu. Tas izpilda tos pašus iekšprocesa validatorus, ko izpilda platformas pievienošanas process, tāpēc nav novirzes starp "tas tika validēts manā datorā" un "platforma to pieņēma".

Komanda Karodziņi Ko tas dara Izejas kodi
scaffold <name> --tier full-service\|ui-only\|skills-only, --dir <path>, --print Ieraksta jaunu spraudņa direktoriju; --print izdrukā tikai manifestu 0 ierakstīts · 1 atteicās pārrakstīt · 2 nepareizs lietojums
validate <file> Validē nexus.manifest.json vai .ts vai .js moduli, kas to eksportē 0 derīgs · 1 nederīgs vai nelasāms · 2 nepareizs lietojums
migrate <file> --write Paceļ v1 manifestu uz v2 un izdrukā to vai ieraksta to esošajā vietā 0 · 1 · 2, kā norādīts iepriekš
guide --manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint Atveido patērētāja ceļvedi no manifesta un jūsu apraksta; --check salīdzina ar krātuvē apstiprināto kopiju un neko neieraksta 0 · 1 novirze vai koda kvalitātes pārkāpums · 2 nepareizs lietojums
help Izdrukā lietojumu 0

Sagataves izveide un trīs līmeņi

npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-service

--tier noklusējuma vērtība ir full-service. Karkasa veidotājs atsakās rakstīt direktorijā, kas jau pastāv, un manifests, ko tas ieraksta, jau iziet validāciju; tas nekad neizdod nederīgu manifestu.

Izvēlieties līmeni pēc tā, kas ir jūsu spraudnim.

Līmenis Ir Jādeklarē
skills-only Manifesta prasmes un nekas cits skills[], ar vismaz vienu ierakstu
ui-only Priekšgala virsma čaulas iekšienē frontend
full-service Aizmugursistēma un priekšgals, parasti ar savu shēmu backend un frontend; un, tā kā tam ir aizmugursistēma, runtime.healthCheck

Ja neesat pārliecināts, izveidojiet full-service karkasu un izdzēsiet to, kas jums nav nepieciešams. Darot pretēji, būs jāuzraksta daļas, kuras jums būtu devusi veidne.

Pilna servisa veidnes apskats

Veidne ir atsauces spraudnis, kas uzbūvēts pēc stingra parauga, kuru pieņem katra nākamā nodaļa. Klonējiet tās formu, nevis parauga loģiku.

Ceļš Kas tas ir
nexus.manifest.json v2 manifests: no jauna formulētie trīs likumi, maršrutu tabula un tās tiesību reģistrs
src/config.ts Konfigurācijas ielādētājs. Viena specifikācija, nolasīta vienreiz, katra problēma apkopota, pirms process atsakās sāknēties
src/scope.ts Vienīgais fails, kas pārvērš pieprasījumu par tvērumu, ar SDK stingro pilnvaru pārbaudītāju un diviem režīmiem: personas uzrādītāja pilnvaru un platformas pakalpojuma izsaukumu
src/db.ts Katrs priekšraksts veido tenantFence() un darbojas withScopedTx iekšienē
src/uno.ts Vienīgais nosūtīšanas fails: viens URL, viens klients, slēgts atļauto saraksts
src/routes/*.ts health (anonīms, precīzs ceļš), /api maršruti (ar tvērumu) un /internal atpakaļizsaukums (pakalpojuma aizsargāts)
src/skills/sentiment.ts Deterministiska host_callback prasme; aizstājiet leksikonu ar savu loģiku
src/server.ts Kompozīcijas sakne: vienreiz instalē atteikumu virsgrāmatu, gaida datubāzi (ierobežoti), pēc tam pirms klausīšanās izpilda izolācijas un virsgrāmatas pārbaudes
migrations/000_tenancy.sql Atveido nexus-tenancy render karkasa izveides laikā: lomas, shēma, rindu līmeņa drošības veidne
migrations/001_init.sql Divas tabulas ar nomnieka vadošo salikto atslēgu un saliktu, nomnieku nesošu ārējo atslēgu
migrations/002_refusal_ledger.sql Tabula, kurā raksta atteikumu virsgrāmata
scripts/ci/required-env Izdrukā sāknēšanai nepieciešamo vides mainīgo nosaukumus kā JSON
scripts/ci/shadow-migrate-*.sh Konveijera migrācijas izmēģinājuma izpilde caur nexus-migrate
gates/ Vārtu izņēmumu direktorijs: tukšs, kas ir pareizais stāvoklis jaunam spraudnim
test/ Testi tvērumam, maršrutiem, datubāzei, nosūtīšanai un sāknēšanai, ar tvēruma dublikātiem, ko ievada katrs tests
Dockerfile Ne-saknes attēls (lietotāja ID 10001) ar migrācijām tā iekšienē

Dažus no šiem failiem ir vērts apskatīt tuvāk.

src/config.ts ievēro divus noteikumus. Tas apkopo katru problēmu, pirms izmet kļūdu, tāpēc viena restartēšana nosauc visus piecus trūkstošos mainīgos, nevis piecas restartēšanas nosauc pa vienam katrā. Un tas iestata noklusējuma vērtību tikai tad, kad nepareiza vērtība nevar radīt klusu nepareizu atbildi: PORT noklusējuma vērtība var būt 8080, jo nepareizs ports redzami neizdodas piesaistē, kamēr DATABASE_URL un UNO_DISPATCH_URL ir obligāti un tiem jābūt klastera iekšējām adresēm. Publiska adrese sāknēšanas laikā tiek atteikta.

node scripts/ci/required-env
["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]

Pašas veidnes tests izpilda šo failu un salīdzina tā izvadi ar nosaukumiem, ko konfigurācijas specifikācija atzīmē kā obligātus, tāpēc obligātā mainīgā pievienošana, neatjauninot sarakstu, izraisa npm test kļūmi.

src/server.ts neklausās, kamēr datubāze neatbild, un tas ierobežo gaidīšanu līdz 120 sekundēm, reģistrējot katru neveiksmīgo mēģinājumu ar tā cēloni. Pēc tam tas secīgi pierāda, ka lietotnes loma nevar atkārtoti piesaistīt nomnieku un katrai tabulai ir piespiesta rindu līmeņa drošība, ka katra poda pūls atbilst lomas savienojumu limitam un ka atteikumu virsgrāmatas tabula var pieņemt rindu. Atteikums no jebkura no šiem trim tiek izdrukāts pilnībā, un process beidzas ar kodu 2.

v2 manifests, lauku pa laukam

Manifests ir spraudņa mašīnlasāms līgums ar platformu. Tas tiek validēts, kad jūs to veidojat, kad platforma to pievieno, un nepārtraukti pēc tam. Shēma ir additionalProperties: false katrā līmenī: ja jūsu spraudnim ir sadaļa, tai ir rekvizīts, un nedeklarēta atslēga tiek atteikta. Risinājums vienmēr ir izmantot pareizo neobligāto rekvizītu.

Obligātais kodols

Lauks Noteikums
manifestVersion Tieši "2". v1 dokuments tiek migrēts, nekad netiek atkārtoti validēts esošajā vietā
name ^[a-z0-9]+([-.][a-z0-9]+)*$, ne vairāk kā 64 rakstzīmes. Spraudņa id, ko izmanto reģistrācijā, nosūtīšanas nosaukumvietu piešķiršanā un nomnieka tvēruma rindās. Spraudnim, kas deklarē prasmes, ir nepieciešams arī nosaukums bez punkta un bez vadošā cipara
displayName No 1 līdz 120 rakstzīmēm
version Semantiskā versija; jūsu pašu laidienu cikls
description, author, license Vismaz viena rakstzīme katrā
tier skills-only, ui-only vai full-service
trust core, verified, community vai untrusted
runtime Obligāti: executionMode, isolationLevel (no 1 līdz 4), entrypoint. Neobligāti: nodeVersion, healthCheck, readinessCheck, livenessCheck, katrs ir ceļš, kas sākas ar /. Režīms tiek atvasināts no līmeņa: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker
architecture compute, ai un deploy, no jauna formulētie trīs platformas likumi. Validators fiksē formulējumu

Spraudnim, ko būvējat savai instalācijai, trīs teikumi ir šādi. ai teikums attiecas uz mākslīgo intelektu (MI) un ir vieta, kur norādīt, ka spraudnis neglabā modeļu akreditācijas datus.

"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."
}

Maršrutu tabula: api un rights

api ir nepieciešams version un basePath, un neobligāti websocket (path, auth) un endpoints[]. Maršrutu tabula ir spēcīgākā ideja shēmā: vārti salīdzina to ar maršrutiem, kurus jūsu kods patiešām reģistrē, abos virzienos, tāpēc manifests ir pārbaudāms līgums, nevis dokumentācija.

Katram galapunktam ir nepieciešams method (GET, POST, PUT, PATCH vai DELETE) un path. Pārējais:

Lauks Ko tas norāda
auth Viena no piecām klasēm: scope (personas maršruts, aiz tvēruma sarga), service-key un internal (no servera uz serveri, nekad nav sasniedzams no pārlūkprogrammas), public (vienmēr tikai precīzs ceļš ar allowAnonymous) un device (mašīna ar saviem akreditācijas datiem, aiz ierīces sarga)
right Obligāts katrā maršrutā, ko apkalpo tvēruma sargs, un atteikts jebkurā citā: tiesību nosaukums rights reģistrā
needsUnit Maršruts atsaka, ja nevar atrisināt izsaucēja vienību
allowAnonymous Tikai precīzas atbilstības atļauto saraksts. Prefiksa noteikums ir veids, kā /health-of-tenant-42 kļūst publisks
group, serves, screens Zem release bloka: spēju grupa, ko maršruts apkalpo, ko tas atbild, kad šīs grupas licencētais līdzeklis ir bloķēts (data, teaser, sighting vai ask), un ekrāni, ko tas apkalpo
query required (katrs nosaukums ar piemēra vērtību) un allowed: vaicājuma parametri, kurus maršruts lasa
body example: rakstīšanas maršruta piemēra pamatteksts, tāds, ko pieņem tā paša validators. Nekad uz GET

rights ir reģistrs, ko šie maršruti nosauc. Katrām tiesībām ir roles (griesti) un neobligāti summary, never (lomas, kas nekad nedrīkst tās izmantot, neatkarīgi no tā, kas vēl tām pieder), barred (paša produkta vārdi never lomas atteikšanai), seat (ir nepieciešama arī aktīva sēdvieta), self (tās pieder katrai verificētai personai, tiesībām pār savu sesiju), grants (turētāji piešķir sēdvietas; ne vairāk kā vienas tiesības tā nosaka), licence (licencēts līdzeklis, kas jāietver organizācijas licencei) installation (pieder tikai pašas instalācijas administratoriem) un platform (pieder tikai Adverant platformas administratoriem; tas nenosauc nekādas lomas). Tiesību nosaukumos ir vismaz viens punkts: 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 atsaka tvēruma maršrutu bez tiesībām (ENDPOINT_RIGHT_MISSING), tiesības, kuru trūkst reģistrā (ENDPOINT_RIGHT_NOT_REGISTERED), un tiesības maršrutā, ko neapkalpo neviens sargs (ENDPOINT_RIGHT_UNGUARDED). Tas atsaka arī reģistru, kas ir pretrunā pats ar sevi, un divus viena maršruta pierakstus (:id un :recordId) kā DUPLICATE_ENDPOINT.

Jūsu dati: databases, schema un db

schema ir vienīgā Postgres shēma, kas pieder spraudnim. public, plugins, auth un nexus ir aizliegti, un, ja databases[] arī nosauc Postgres shēmu, abām ir jāsakrīt.

databases[] deklarē katru krātuvi pēc dzinēja: postgresql (schema, tables, migrations un granted, tabulas, kuras cita organizācija var lasīt saskaņā ar reģistrētu piešķīrumu), neo4j (schemas), qdrant (collections) vai redis (purpose).

db glabā sesijas limitus katram savienojumam, ko spraudnis atver, un tie ir deklarēti šeit, nevis iekodēti, lai gan recenzents, gan izvietojums varētu tos izlasīt:

Lauks Ko tas ierobežo
maxConnections Pūls uz vienu repliku
pods Maksimālais podu skaits, kas vienlaikus tur pūlu, replikas plus pakāpeniskās atjaunināšanas pieaugums. Katras lomas savienojumu limits tiek atveidots kā maxConnections × pods; ja to izlaidīsiet, definePlugin brīdinās DB_PODS_UNDECLARED
statementTimeoutMs Viens priekšraksts
idleInTransactionTimeoutMs Atvērta transakcija, kas neko neizpilda
workMemKB Viens kārtošanas vai jaukšanas mezgls, uz vienu mezglu, nevis uz vienu vaicājumu
piiMask[] table.column ieraksti, kas satur personas datus, maskēti pārvaldītajā SQL konsolē un žurnālos

Prasmes un rīki: skills, mcpTools, entitlements

skills[] glabā manifesta prasmes; 2.20. nodaļā, Prasmes, ir apskatīti to lauki un līmeņi. mcpTools[] glabā MCP (Model Context Protocol) rīkus, ko spraudnis publicē, kur katrs ir name, description un inputSchema bez augšējā līmeņa oneOf, allOf vai anyOf.

entitlements pieprasa featureIdPattern un pieņem alwaysOn[], source un store. Paraugs nosauc nosaukumvietu, kurā atrodas jūsu līdzekļu id, parasti spraudņa name plus viens segments, ko jūsu kods aizpilda katrai virsmai. alwaysOn[] ir īss, precīzs saraksts, kam jāatbild pat tad, ja nevar iegūt tiesību spriedumu: veselība, gatavība, pierakstīšanās un iestatījumi, kas administratoram nepieciešami tiesību salabošanai.

Izmaiņu vadība: changePolicy

"changePolicy": {
  "enabled": true,
  "classes": ["website", "bff", "migration"],
  "approvals": { "website": 1, "bff": 1, "migration": 2 }
}

Apstiprinājumi tiek skaitīti kā atšķirīgas personas, un persona, kas ierosināja izmaiņas, nekad nav viena no tām; bez abām šīm daļām "divi apstiprinājumi" kļūst par vienu personu, kas noklikšķina divreiz. enabled: true pieprasa classes, un katrai nosauktajai klasei ir nepieciešams savs skaits. Klase, kuru izlaižat, ir nepārvaldīta, kas ir leģitīma izvēle, kuru shēma liek jums pierakstīt.

Kas jūs esat: domains, branding, routing

domains[] (katrs primary un aliases[]; domain ir viena domēna forma) uzskaita, kur spraudnis atbild. branding pieprasa appName un pieņem tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId un gaId. Viss iekš branding ir publisks: pierakstīšanās lapa to izlasa, pirms kādam ir akreditācijas dati, tāpēc tajā nekad nav noslēpuma vai iekšējās adreses. routing (type, gateway, virtualService) ir paredzēts spraudņiem, kas apraksta paši savu maršrutēšanu.

Izmēru noteikšana un pārējais

resources pieprasa cpuMillicores (no 10 līdz 64,000) un memoryMB (no 16 līdz 262,144), un pieņem diskGB, timeoutMs, port un wsPort. backend glabā port, healthPath, apiPrefix, framework un platformClients[], SDK klientus, kurus jūsu aizmugursistēma importē pēc nosaukuma. Saraksts ir slēgts, un vārti pārbauda to pret jūsu importiem. Shēma atļauj četrpadsmit nosaukumus: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin un uno, plus vienu klientam, kas atbild uz plāna tiesību atteikumiem, kurš saglabā iekšēju nosaukumu. Līdzekļu tiesību klients, runtime/entitlements, nav viens no tiem un nekad nenonāk sarakstā, jo jūsu entitlements bloks to jau deklarē, un aizmugursistēma, kas to importē bez entitlements bloka, neiziet tos pašus vārtus. frontend glabā basePath, mountPath un framework. nexus glabā minVersion, maxVersion, capabilities[] un permissions[].

Katrs no atlikušajiem blokiem ir paredzēts vienam uzdevumam:

Bloks Mērķis
settings Jūsu iestatījumi koplietotajā ietvarā: groups un keys, iestatīti līmeņos, ko katrs nosauc
people sweep (service, port): organizācijas dalībnieki, sinhronizēti no identitātes pakalpojuma, ar izslēgtām sēdvietām, kad kāds aiziet
ontology entityTypes un relationshipTypes: tipizētais grafs, kas tiek glabāts jūsu pašu shēmā
release groups un frame: spēju grupas, kurās jūsu maršruti tiek pakāpeniski izvietoti, vispirms izlaižot kā kanārijputniņu
cells[] Spraudnis, kas sastāv no vairākām izvietojamām vienībām: katrai name, kind, entrypoint, port, wsPort
pricing model, currency, tiers[] jūsu kataloga ierakstam
marketplace category, icon, screenshots, documentation, featured
compliance instruments[], dataResidency, sovereignty
developer, repository, keywords Kas to publicē un kur atrodas tā kods
metrics, atlas Divi apzināti atvērti objekti jūsu pašu metrikas nosaukumiem un arhitektūras dokumentācijas ģenerēšanai

Ko shēma nevar pateikt

JSON Schema nosaka formu; definePlugin pievieno noteikumus, kurus shēma nevar izteikt. Prasmes classification nedrīkst pārsniegt uzticamības griestus. Tikai core un verified spraudņi drīkst deklarēt tool_using un llm_only prasmes. Katram deklarētajam ceļam jābūt relatīvam un ar to pašu izcelsmi, bez shēmas, bez // un bez atpakaļvērstās slīpsvītras, jo URL parsētājs pārvērš \ par / un /\evil.example/x atrisinās kā starpizcelsmju. Katrs noteikums, ko reģistra sinhronizācija piemēro prasmei, vispirms tiek piemērots šeit, ar pašas sinhronizācijas kodu, tāpēc validate un sinhronizācija nosauc pārkāptu noteikumu vienādi.

Validācija un pāreja no 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

Kļūme izdrukā precīzu ceļu un, sinhronizācijas noteikumam, vispirms kodu. Padariet to par apstiprināšanas āķi (commit hook).

v1 manifests tiek pacelts mehāniski. migrate pievieno trīs likumu teikumus, pārvieto domain uz domains[] un atsakās izgudrot ieejas punktu, kura jums nebija. Tas validē rezultātu pirms jebkā izdrukāšanas vai ierakstīšanas, tāpēc migrācija nekad nepārvieto kļūmi no rīka uz jūsu krātuvi.

npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --write

Izlasiet izmaiņu salīdzinājumu (diff), pirms to apstiprināt. Likumu teikumi, ko tas pievieno, ir formulējums, kuru fiksē validators; savai instalācijai iestatiet deploy uz iepriekš parādīto teikumu.

Nomnieku vides atveidošana un lomu nodrošināšana

Jūs nekad nerakstāt savus lomu piešķīrumus vai rindu līmeņa drošības veidni ar roku. nexus-tenancy render tos uzraksta no manifesta schema un db:

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sql

Atveidotais fails izveido piecas lomas shēmai, katru ar to, kas tai nedrīkst piederēt: migratoru, kas var kļūt tikai par īpašnieku, īpašnieku, kas nevar pieteikties, lietotnes lomu pieprasījuma ceļam, pārskatu lomu, kas redz tikai kopsavilkumus, un virsgrāmatas lomu, kas var tikai pievienot. Nevienai lomai nepieder BYPASSRLS. Vienīgais veids, kā piesaistīt nomnieku, ir viena datubāzes funkcija, un set_config ir atsaukts visām lomām, izņemot īpašnieku.

Lietots nomnieku izolācijas fails nekad netiek rediģēts. Izmaiņas ir revīzija ar savu 0. numura failu, un lasīšanas sēdvieta starporganizāciju piešķīrumiem tiek piegādāta šādā veidā, kā 2. revīzija. --graph atveido abas tipizētā grafa tabulas, kuras jūsu ontology deklarē kā jūsu nākamo numurēto migrāciju.

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

Nomnieku izolācijas fails izveido tieši tās lomas, kā kuras izpildītājs pieslēdzas, tāpēc to lieto datubāzes īpašnieks ar 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> ir savienojuma virkne datubāzes īpašniekam, un <dir> ir privāts direktorijs. Nodrošināšana lieto bāzes nomnieku izolācijas failu un katru revīziju pēc kārtas, ieraksta migrator.url un app.url (un seat.url, tiklīdz pastāv 2. revīzija) iekš <dir> ar režīmu 0600, un neizdrukā neko slepenu. Tā iestata katras lomas savienojumu limitu no db.maxConnections × db.pods katrā izpildes reizē. Atkārtota izpilde saglabā esošās paroles, ja vien jūs nelūdzat citādi: --passwords <dir> iestata tās no failiem un --rotate <roles> piešķir nosauktajām lomām jaunas paroles. Pārvērtiet šos failus par sava izvietojuma noslēpumiem.

Pēc tam lietošana pieslēdzas ar migratora savienojuma virkni, ko ierakstīja nodrošināšana:

DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.json

Tā izpilda failus no 001 un tālāk kā migrators, katru failu zem SET ROLE <schema>_owner, viena transakcija uz vienu failu. Tā uztur virsgrāmatu, <schema>.schema_migrations, ar katra faila kontrolsummu; lietots fails, kura baiti ir mainījušies, tiek atteikts pēc nosaukuma (CHECKSUM_DRIFT), nekad netiek izpildīts atkārtoti un nekad netiek izlaists. Katrs gaidošais fails tiek parsēts ar īsto Postgres gramatiku, pirms tiek izpildīts pirmais, tāpēc atteikums atstāj datubāzi neskartu. Vienīgā galvene, kas failam var būt, ir -- nexus-migration: transaction=file|per-statement, ar neobligātiem bloķēšanas un priekšrakstu noildzes laikiem; per-statement ir paredzēts CREATE INDEX CONCURRENTLY.

Kontroles barjeras

nexus-gates izpilda divdesmit divus vārtus. Katri iekodē vienu defektu klasi, lai to nevarētu piegādāt divreiz, un katriem ir paštests, kas pierāda, ka tie neizdodas uz sagataves, kas uzbūvēta to nostrādināšanai. Izpildiet tos pirms koda nosūtīšanas (push):

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test
Vārti Ko tie noķer
scope-adherence /api maršrutu bez tvēruma sarga; anonīmu ceļu, kas nav precīzs deklarētais ceļš; ierīces maršrutu bez ierīces sarga vai ar personas sargu tam blakus
one-fence Nomnieka predikātu, kas definēts jebkur citur, nevis vienā vietā, ieskaitot ar roku rakstītu sēdvietas vai piešķīruma nožogojumu
sql-fence Priekšrakstu, kas lasa vai atjaunina tvēruma tabulu bez nožogojuma, jebkurā FROM, JOIN, USING vai UPDATE mērķī
migrations-are-scoped Tabulu, kurai trūkst ass, nomnieka vadošās saliktās atslēgas, nomnieku nesošas ārējās atslēgas vai demonstrācijas kolonnas
migrations-commit-what-they-open Migrāciju, kuras BEGIN skaits nesakrīt ar tās COMMIT un ROLLBACK skaitu
no-direct-compute Tiešu izsaukumu modeļa nodrošinātājam, dzinējam, rindai vai darbplūsmas resursdatoram; otru nosūtīšanas URL lasītāju
no-credentials Modeļa nodrošinātāja akreditācijas datus, kas ir lasāmi krātuvē vai vidē
crud-adherence Mutējošu maršrutu, kura tiesību pārbaude nenosauc neko reģistrā
blocked-backends Maršrutu, kas netiek ne apkalpots, ne bloķēts pēc nosaukuma, ne atteikts pēc likuma, ne arī pieder citur
every-test-runs Testus, kurus testa skripta šablons (glob) nekad nesasniedz
tiles-are-invariant Nomniekam nemainīgu kešotu šuvi, kas lasa nomnieka vērtību vai izlaiž autentifikāciju
api-contract Reģistrētu maršrutu, ko manifests nedeklarē, vai deklarētu maršrutu, ko kods nekad nereģistrē
rls-present Tabulu bez piespiestas rindu līmeņa drošības; SECURITY DEFINER funkciju bez piesaistīta search_path
no-set-config Spraudņa kodu, kas pats piesaista nomnieka iestatījumu
db-role-honest Pieprasījuma ceļu, kas pieslēdzas kā īpašnieks vai migrators, vai pieprasa SUPERUSER vai BYPASSRLS
platform-clients SDK klientu, kas ir importēts, bet nav uzskaitīts iekš backend.platformClients, vai ir uzskaitīts, bet nekad nav importēts
rights-register Tvēruma maršrutu bez deklarētām tiesībām; tiesību pārbaudi ārpus reģistra
refusal-ledger Deklarētu atteikumu tabulu bez instalētas virsgrāmatas, vai atteikuma pamattekstu, kas nosūtīts, to apejot
grants-declared Piešķirtu tabulu, ko manifests nedeklarē; ar roku izdalītas lasīšanas sēdvietas privilēģijas
people-declared people bloku bez tā tīrīšanas maršruta, sarga un tabulām
functions-closure Azure Functions spraudni, kura apkalpotie maršruti un deklarētie maršruti nesakrīt
declared-input Apstrādātāja vaicājuma parametru sarakstu, kas nesakrīt ar maršruta deklarēto query

gates/ direktorijs glabā piecus izņēmumu failus, kurus vārti var lasīt (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json un invariant-seams.json), viens iemesls katram ierakstam. Tukšs iemesls skaitās kā neesošs ieraksts, un ieraksts, kas nosauc kaut ko tādu, kas vairs nepastāv, izraisa vārtu kļūmi. Jūs varat tur ievietot arī savus vārtu moduļus, un nexus-gates tos paņem blakus iebūvētajiem.

Saderība
Saderība
Saderība rāda, kura SDK versija darbojas ar kuru platformas versiju, no ātrā sākuma nakts izpildēm. Netestēts pāris tā arī norāda, un neveiksmīgs pāris nosauc izmaiņas, kas to salauza.

Veidnes konveijers

Veidne nepiegādā ar roku rakstītu darbplūsmu. Tās konveijera konfigurācija nosauc Dockerfile, vienīgo būvēšanas argumentu (reģistra pilnvaru), migrācijas izmēģinājuma izpildi un sāknēšanas pārbaudi, kā arī vārtus, kurus izpilda sapludināšanas rinda. Secība ir tāda secība, kādā jūs vēlētos saņemt kļūmi.

  1. npm ci
  2. npm run typecheck
  3. npm run build
  4. npm test
  5. npm run validate:manifest, kas ir create-nexus-plugin validate nexus.manifest.json
  6. npm run gates, kas ir nexus-gates --self-test
  7. node scripts/ci/required-env

Ap attēlu tiek veiktas vēl divas pārbaudes. Migrācijas izmēģinājuma palaišana piemēro katru failu pagaidu Postgres datubāzei, pirms attēlu var izlaist, izmantojot to pašu izpildītāju, ko izmanto produkcijas vide: nexus-migrate provision vienu reizi kā superlietotājam, pēc tam katru numurēto failu kā migratoram. palaišanas pārbaude startē uzbūvēto attēlu ar tā ieejas punktu un katru mainīgo, ko izvada required-env, novirzot uz aizstājējiem, kas pieņem savienojumus un nekad neatbild. Serveris gaida datubāzi savā ierobežotajā laika logā, un šī gaidīšana ir sekmīgas izpildes signāls; konfigurācijas ielādētājs, kas atsakās palaisties, izraisa būvējuma kļūmi tur, nevis produkcijas vidē.

Būvēšana Community redakcijā
Būvēšana Community redakcijā
Community versijā izstrādātājs iegūst tos pašus standarta ceļus, izstrādes telpu un datu zarus vienā serverī ar kodu savā Git mitinātājā. Pirmsprodukcijas vide, izmēģinājuma vienības un maskētas reālo datu kopijas ir pieejamas Enterprise versijā.

Izmaksas

SDK pieņem lēmumus jūsu vietā, un dažus no tiem jūs būtu pieņēmuši citādi. Manifests noraida atslēgas, kuras tas nepazīst, maršrutu tabulai ir precīzi jāatbilst jūsu kodam, datubāzes lomas nav jūsu ziņā, un kontrolpunkti pārtrauc būvējumu, ja lasīšanas operācijai trūkst tiesību. Izstrādājot savu pirmo spraudni, es pavadīju dienu, strīdoties ar api-contract par maršrutu, ko biju reģistrējis un aizmirsis deklarēt. Tam bija taisnība; maršruts nebija aizsargāts. Rēķinieties, ka pirmā spraudņa izstrāde šķitīs lēna, un rēķinieties, ka otrajam būs nepieciešama trešdaļa no šī laika.