PrisijungtiUžsisakyti pristatymą

2.21 skyrius

Įskiepių SDK

Įskiepių SDK (programinės įrangos kūrimo rinkinio) diegimas, jo komandinės eilutės įrankiai, pilnos tarnybos šablono apžvalga, v2 manifesto laukai po vieną ir dvidešimt du barjerai, užtikrinantys, kad įskiepis laikytųsi taisyklių.

Šį puslapį iš originalo anglų kalba išvertė DI. Jei kas nors neaišku, remkitės puslapiu anglų kalba. Skaityti šį puslapį anglų kalba

22 min. skaitymo

Mano antrajam papildiniui sukurti prireikė trečdalio laiko, kurį skyriau pirmajam, ir beveik visą sutaupymą lėmė SDK (programinės įrangos kūrimo rinkinys). Pirmą kartą parašiau aprėpties patikrą, konfigūracijos įkėliklį ir migracijų vykdyklę, o recenzentas grąžino kiekvieną iš jų. Antrą kartą paleidau vieną karkaso komandą, ištryniau pavyzdinį nuotaikų analizės įgūdį ir savo dienas skyriau anomalijų peržiūros įrašams, kurių iš tikrųjų reikėjo mūsų skrydžio dinamikos komandai.

@adverant-nexus/plugin-sdk yra vienas npm paketas. Jame yra v2 manifesto schema ir ją skaitantys tikrintuvai (definePlugin, defineSkill), vykdymo aplinkos moduliai, kuriuos jūsų papildinys importuoja aprėpčiai, duomenų bazei, siuntimui ir kitoms reikmėms, testavimo pagalbinės priemonės, atitikties vartai ir komandinės eilutės įrankiai. Šiame skyriuje aprašoma, kaip jį įdiegti, taip pat įrankiai, šablonas, manifestas ir vartai. 2.22 skyriuje „Papildinio vykdymo aplinka“ aprašomi vykdymo aplinkos moduliai jūsų veikiančiame kode.

Jo diegimas

Paketas gaunamas iš Adverant registro adresu https://registry.adverant.ai/npm/, niekada ne iš viešojo npm registro, ir jums reikia atsisiuntimo prieigos rakto iš jūsų paskyros puslapio „Pull tokens and install commands“. Nukreipkite @adverant-nexus aprėptį į registrą savo saugyklos faile .npmrc:

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

<pull-token> yra prieigos raktas iš jūsų paskyros puslapio. Konvejeryje perduokite jį iš slapto kintamojo ir niekada jo neįtraukite į saugyklą; šablono Dockerfile atsisako kurti atvaizdą be jo ir, įvykdžius npm ci, ištrina .npmrc iš kūrimo etapo, todėl prieigos raktas niekada nepatenka į atvaizdą.

Tada tiksliai užfiksuokite versiją:

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

Pirmą kartą diegdami įtraukite package-lock.json į saugyklą. Šablono atvaizdo kūrimas vykdo npm ci ir atsisako grįžti prie npm install: užrakto failas yra sutartis. Pačiam SDK reikia bent Node 18; šablonas skirtas Node 20.

Komandinės eilutės įrankiai pateikiami pakete, todėl kiekvienoje šios dokumentacijos komandoje paketas ir jo versija nurodomi su npx -p. Atskirai npx create-nexus-plugin ieškomas viešajame registre, o tas pavadinimas nėra šis paketas.

Komandinės eilutės įrankiai

Įrankis Ką daro
create-nexus-plugin Sukuria papildinio karkasą, patikrina manifestą, perkelia v1 manifestą į v2 ir sugeneruoja vartotojo vadovą jūsų sąsajos kūrėjui
nexus-tenancy Iš manifesto sugeneruoja jūsų schemos nuomininkų atskyrimo SQL: vaidmenis, suteikimus, eilučių lygio saugos šabloną ir grafo lenteles
nexus-migrate Taiko jūsų migracijas: vieną kartą sukuria vaidmenis, tada kiekvieną numeruotą failą vykdo migratoriaus vaidmeniu
nexus-gates Vykdo visus atitikties vartus ir kiekvienų vartų savitikrą

create-nexus-plugin neatlieka jokių tinklo užklausų ir neįkelia jokio nuotolinio kodo. Jis vykdo tuos pačius procese veikiančius tikrintuvus, kuriuos vykdo platformos prijungimo procesas, todėl nėra neatitikimo tarp „mano kompiuteryje patikrinimas praėjo“ ir „platforma jį priėmė“.

Komanda Vėliavėlės Ką daro Užbaigimo kodai
scaffold <name> --tier full-service\|ui-only\|skills-only, --dir <path>, --print Sukuria naują papildinio katalogą; --print išveda tik manifestą 0 įrašyta · 1 atsisakyta perrašyti · 2 netinkamas naudojimas
validate <file> Patikrina nexus.manifest.json arba .ts ar .js modulį, kuris jį eksportuoja 0 tinkamas · 1 netinkamas arba neperskaitomas · 2 netinkamas naudojimas
migrate <file> --write Perkelia v1 manifestą į v2 ir jį išveda arba įrašo vietoje 0 · 1 · 2, kaip nurodyta aukščiau
guide --manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint Iš manifesto ir jūsų aprašomojo teksto sugeneruoja vartotojo vadovą; --check palygina su įtraukta kopija ir nieko neįrašo 0 · 1 neatitikimas arba stiliaus tikrinimo pažeidimas · 2 netinkamas naudojimas
help Išveda naudojimo informaciją 0

Ruošinių kūrimas ir trys pakopos

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

--tier numatytoji reikšmė yra full-service. Karkaso generatorius atsisako rašyti į jau esamą katalogą, o jo įrašytas manifestas jau praeina patikrinimą; jis niekada nesukuria netinkamo manifesto.

Pakopą pasirinkite pagal tai, ką turi jūsų papildinys.

Pakopa Turi Privalo deklaruoti
skills-only Tik manifesto įgūdžius skills[], su bent vienu įrašu
ui-only Sąsajos paviršių apvalkale frontend
full-service Užpakalinę ir priekinę dalis, paprastai su savo schema backend ir frontend; o kadangi turi užpakalinę dalį, ir runtime.healthCheck

Jei nesate tikri, sukurkite full-service karkasą ir ištrinkite tai, ko jums nereikia. Einant priešinga kryptimi tektų rašyti dalis, kurias jums būtų pateikęs šablonas.

Pilnos tarnybos šablono apžvalga

Šablonas yra pavyzdinis papildinys, sukurtas pagal griežtą modelį, kurį numato visi tolesni skyriai. Kopijuokite jo struktūrą, ne jo pavyzdinę logiką.

Kelias Kas tai yra
nexus.manifest.json v2 manifestas: trys dėsniai, pakartoti iš naujo, maršrutų lentelė ir jos teisių registras
src/config.ts Konfigūracijos įkėliklis. Viena specifikacija, perskaitoma vieną kartą; visos problemos surenkamos prieš procesui atsisakant paleisti
src/scope.ts Vienintelis failas, kuris užklausą paverčia aprėptimi, su griežtu SDK prieigos rakto tikrintuvu ir dviem režimais: asmens nešėjo prieigos raktu ir platformos tarnybos iškvietimu
src/db.ts Kiekvienas sakinys sudaromas su tenantFence() ir vykdomas withScopedTx viduje
src/uno.ts Vienintelis siuntimo failas: vienas URL, vienas klientas, uždaras leidžiamųjų sąrašas
src/routes/*.ts health (anoniminis, tikslus kelias), /api maršrutai (su aprėptimi) ir /internal atgalinis iškvietimas (saugomas tarnybos apsaugos)
src/skills/sentiment.ts Deterministinis host_callback įgūdis; pakeiskite žodyną savo logika
src/server.ts Kompozicijos šaknis: vieną kartą įdiegia atsisakymų žurnalą, laukia duomenų bazės (ribotą laiką), tada prieš pradėdamas klausytis atlieka izoliacijos ir žurnalo patikras
migrations/000_tenancy.sql Sugeneruojama nexus-tenancy render kuriant karkasą: vaidmenys, schema, eilučių lygio saugos šablonas
migrations/001_init.sql Dvi lentelės su sudėtiniu raktu, prasidedančiu nuomininku, ir sudėtiniu, nuomininką apimančiu išoriniu raktu
migrations/002_refusal_ledger.sql Lentelė, į kurią rašo atsisakymų žurnalas
scripts/ci/required-env Išveda paleidimui būtinų aplinkos kintamųjų pavadinimus JSON formatu
scripts/ci/shadow-migrate-*.sh Konvejerio bandomasis migracijų paleidimas per nexus-migrate
gates/ Vartų išimčių katalogas: tuščias, ir tai yra teisinga naujo papildinio būsena
test/ Aprėpties, maršrutų, duomenų bazės, siuntimo ir paleidimo testai su aprėpties pakaitalais, kuriuos įterpia kiekvienas testas
Dockerfile Ne root atvaizdas (naudotojo ID 10001) su jame esančiomis migracijomis

Kai kuriuos iš šių failų verta panagrinėti atidžiau.

src/config.ts laikosi dviejų taisyklių. Prieš išmesdamas klaidą jis surenka visas problemas, todėl vienas paleidimas iš naujo įvardija visus penkis trūkstamus kintamuosius, užuot penkiems paleidimams iš naujo įvardijus po vieną. Be to, numatytąją reikšmę jis nustato tik tada, kai klaidinga reikšmė negali lemti tylaus klaidingo atsakymo: PORT numatytoji reikšmė gali būti 8080, nes dėl klaidingo prievado susiejimas matomai nepavyksta, o DATABASE_URL ir UNO_DISPATCH_URL yra privalomi ir turi būti klasterio vidaus adresai. Viešas adresas atmetamas paleidžiant.

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

Paties šablono testas paleidžia tą failą ir palygina jo išvestį su pavadinimais, kuriuos konfigūracijos specifikacija žymi kaip privalomus, todėl pridėjus privalomą kintamąjį neatnaujinus sąrašo npm test nepavyksta.

src/server.ts nepradeda klausytis, kol neatsako duomenų bazė, o laukimą apriboja 120 sekundžių ir registruoja kiekvieną nepavykusį bandymą su jo priežastimi. Tada jis paeiliui patikrina, kad programos vaidmuo negali iš naujo susieti nuomininko ir kad kiekvienai lentelei priverstinai taikoma eilučių lygio sauga, kad kiekvieno podo telkinys neviršija vaidmens jungčių limito ir kad į atsisakymų žurnalo lentelę galima įrašyti eilutę. Jei bet kuri iš trijų patikrų atsisako, pranešimas išvedamas visas, o procesas baigiamas kodu 2.

v2 manifestas, laukas po lauko

Manifestas yra mašininiu būdu skaitoma papildinio sutartis su platforma. Jis tikrinamas, kai jį rengiate, kai platforma jį prijungia, ir nuolat po to. Schema visuose lygiuose yra additionalProperties: false: jei jūsų papildinys turi skyrių, jam yra savybė, o nedeklaruotas raktas atmetamas. Sprendimas visada yra naudoti tinkamą neprivalomą savybę.

Privalomasis branduolys

Laukas Taisyklė
manifestVersion Tiksliai "2". v1 dokumentas perkeliamas, niekada iš naujo netikrinamas vietoje
name ^[a-z0-9]+([-.][a-z0-9]+)*$, ne daugiau kaip 64 simboliai. Papildinio ID, naudojamas registruojant, siuntimo vardų erdvėse ir nuomininko aprėpties eilutėse. Įgūdžius deklaruojančiam papildiniui taip pat reikia pavadinimo be taško ir neprasidedančio skaitmeniu
displayName Nuo 1 iki 120 simbolių
version Semantinė versija; jūsų pačių leidimų ciklas
description, author, license Kiekvienas bent vieno simbolio
tier skills-only, ui-only arba full-service
trust core, verified, community arba untrusted
runtime Privaloma: executionMode, isolationLevel (nuo 1 iki 4), entrypoint. Neprivaloma: nodeVersion, healthCheck, readinessCheck, livenessCheck, kiekvienas – kelias, prasidedantis /. Režimas nustatomas pagal lygį: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker
architecture compute, ai ir deploy – trys platformos dėsniai, pakartoti iš naujo. Tikrintuvas užfiksuoja formuluotę

Papildiniui, kurį kuriate savo įdiegčiai, šie trys sakiniai skamba taip. ai sakinys apima dirbtinį intelektą (DI) ir yra vieta nurodyti, kad papildinys neturi jokių modelių prisijungimo duomenų.

"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šrutų lentelė: api ir rights

api reikia version ir basePath, o neprivalomai – websocket (path, auth) ir endpoints[]. Maršrutų lentelė yra stipriausia schemos idėja: vartai ją palygina su maršrutais, kuriuos jūsų kodas iš tikrųjų registruoja, abiem kryptimis, todėl manifestas yra patikrinama sutartis, o ne dokumentacija.

Kiekvienam galiniam taškui reikia method (GET, POST, PUT, PATCH arba DELETE) ir path. Visa kita:

Laukas Ką tai reiškia
auth Viena iš penkių klasių: scope (asmens maršrutas už aprėpties apsaugos), service-key ir internal (iš serverio į serverį, niekada nepasiekiami iš naršyklės), public (visada tik tikslus kelias su allowAnonymous) ir device (įrenginys su savais prisijungimo duomenimis, už įrenginio apsaugos)
right Privaloma kiekviename maršrute, kurį aptarnauja aprėpties apsauga, ir atmetama bet kuriame kitame: teisės pavadinimas iš rights registro
needsUnit Maršrutas atsisako, kai nepavyksta nustatyti iškviečiančiojo padalinio
allowAnonymous Tik tikslaus atitikimo leidžiamųjų sąrašas. Dėl prefikso taisyklės /health-of-tenant-42 ir tampa viešas
group, serves, screens release bloke: galimybių grupė, kurią aptarnauja maršrutas, ką jis atsako, kai tos grupės licencijuota funkcija užrakinta (data, teaser, sighting arba ask), ir ekranai, kuriuos jis aptarnauja
query required (kiekvienas pavadinimas su pavyzdine reikšme) ir allowed: užklausos parametrai, kuriuos skaito maršrutas
body example: rašymo maršruto pavyzdinis turinys, kurį priima jo paties tikrintuvas. Niekada GET užklausoje

rights yra registras, kurį įvardija šie maršrutai. Kiekviena teisė turi roles (viršutinę ribą) ir neprivalomai summary, never (vaidmenis, kurie niekada negali jos naudoti, kad ir ką dar turėtų), barred (paties produkto žodžius atsisakant never vaidmeniui), seat (taip pat reikia aktyvios vietos), self (ją turi kiekvienas patvirtintas asmuo – teisėms į savo seansą), grants (turėtojai suteikia vietas; tai gali nurodyti daugiausia viena teisė), licence (licencijuota funkcija, kurią turi apimti organizacijos licencija), installation (ją turi tik pačios įdiegties administratoriai) ir platform (ją turi tik Adverant platformos administratoriai; joje nenurodomi jokie vaidmenys). Teisių pavadinimuose yra bent vienas taškas: 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 atmeta aprėpties maršrutą be teisės (ENDPOINT_RIGHT_MISSING), teisę, kurios registre nėra (ENDPOINT_RIGHT_NOT_REGISTERED), ir teisę maršrute, kurio neaptarnauja jokia apsauga (ENDPOINT_RIGHT_UNGUARDED). Jis taip pat atmeta pats sau prieštaraujantį registrą, o du vieno maršruto užrašymo variantus (:id ir :recordId) – kaip DUPLICATE_ENDPOINT.

Jūsų duomenys: databases, schema ir db

schema yra vienintelė Postgres schema, kuri priklauso papildiniui. public, plugins, auth ir nexus draudžiamos, o jei databases[] taip pat nurodo Postgres schemą, jos turi sutapti.

databases[] kiekvieną saugyklą deklaruoja pagal variklį: postgresql (schema, tables, migrations ir granted – lentelės, kurias kita organizacija gali skaityti pagal užregistruotą suteikimą), neo4j (schemas), qdrant (collections) arba redis (purpose).

db saugo seanso ribas kiekvienai papildinio atidaromai jungčiai; jos deklaruojamos čia, o ne užkoduojamos, kad jas galėtų perskaityti ir recenzentas, ir diegimas:

Laukas Ką riboja
maxConnections Telkinį vienai replikai
pods Didžiausią podų, vienu metu turinčių telkinį, skaičių: replikos plius slenkančio atnaujinimo perteklius. Kiekvieno vaidmens jungčių limitas sugeneruojamas kaip maxConnections × pods; jei jo nenurodysite, definePlugin įspės DB_PODS_UNDECLARED
statementTimeoutMs Vieną sakinį
idleInTransactionTimeoutMs Atvirą transakciją, kuri nieko nevykdo
workMemKB Vieną rūšiavimo arba maišos mazgą, kiekvienam mazgui, ne kiekvienai užklausai
piiMask[] table.column įrašai, kuriuose yra asmens duomenų, maskuojami valdomoje SQL konsolėje ir žurnaluose

Įgūdžiai ir įrankiai: skills, mcpTools, entitlements

skills[] saugo manifesto įgūdžius; jų laukai ir pakopos aprašyti 2.20 skyriuje „Įgūdžiai“. mcpTools[] saugo papildinio skelbiamus MCP (Model Context Protocol) įrankius, kurių kiekvienas turi name, description ir inputSchema be aukščiausio lygio oneOf, allOf ar anyOf.

entitlements reikalauja featureIdPattern ir priima alwaysOn[], source ir store. Šablonas nurodo vardų erdvę, kurioje yra jūsų funkcijų ID, paprastai papildinio name plius vienas segmentas, kurį jūsų kodas užpildo kiekvienam paviršiui. alwaysOn[] yra trumpas, tikslus sąrašas to, kas turi atsakyti net tada, kai teisių sprendimo gauti neįmanoma: būklė, parengtis, prisijungimas ir nustatymai, kurių administratoriui reikia teisėms atkurti.

Pakeitimų valdymas: changePolicy

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

Patvirtinimai skaičiuojami pagal skirtingus asmenis, o pakeitimą pasiūlęs asmuo niekada nėra vienas iš jų; be abiejų šių dalių „du patvirtinimai“ virsta vienu asmeniu, spustelėjusiu du kartus. enabled: true reikalauja classes, o kiekvienai nurodytai klasei reikia savo skaičiaus. Klasė, kurios nenurodote, lieka nevaldoma – tai teisėtas pasirinkimas, kurį schema verčia jus užrašyti.

Kas jūs esate: domains, branding, routing

domains[] (kiekvienas primary ir aliases[]; domain yra vieno domeno forma) nurodo, kur papildinys atsako. branding reikalauja appName ir priima tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId ir gaId. Viskas, kas yra branding, yra vieša: prisijungimo puslapis tai perskaito dar prieš kam nors turint prisijungimo duomenis, todėl ten niekada nėra slaptų duomenų ar vidinių adresų. routing (type, gateway, virtualService) skirtas papildiniams, kurie patys aprašo savo maršrutizavimą.

Dydžio nustatymas ir kita

resources reikalauja cpuMillicores (nuo 10 iki 64,000) ir memoryMB (nuo 16 iki 262,144) bei priima diskGB, timeoutMs, port ir wsPort. backend apima port, healthPath, apiPrefix, framework ir platformClients[] – SDK klientus, kuriuos jūsų backend importuoja pagal pavadinimą. Sąrašas yra uždaras, o patikra jį sutikrina su jūsų importais. Schema leidžia keturiolika pavadinimų: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin ir uno, taip pat vieną klientui, kuris atsako į plano teisių atsisakymus ir išlaiko vidinį pavadinimą. Funkcijų teisių klientas runtime/entitlements nėra vienas iš jų ir niekada neįtraukiamas į sąrašą, nes jūsų entitlements blokas jį jau deklaruoja, o backend, kuris jį importuoja neturėdamas entitlements bloko, neišlaiko tos pačios patikros. frontend apima basePath, mountPath ir framework. nexus apima minVersion, maxVersion, capabilities[] ir permissions[].

Kiekvienas likęs blokas skirtas vienai užduočiai:

Blokas Paskirtis
settings Jūsų nustatymai bendrojoje sistemoje: groups ir keys, nustatomi kiekvieno nurodytuose lygiuose
people sweep (service, port): organizacijos nariai, sinchronizuojami iš tapatybės paslaugos, kai kas nors išeina, vietos išjungiamos
ontology entityTypes ir relationshipTypes: tipizuotas grafas, saugomas jūsų pačių schemoje
release groups ir frame: funkcijų grupės, kuriose etapais diegiami jūsų maršrutai, pirmiausia išleidžiami kaip canary
cells[] Įskiepis, sudarytas iš kelių diegiamų vienetų: kiekvienam name, kind, entrypoint, port, wsPort
pricing model, currency, tiers[] jūsų katalogo įrašui
marketplace category, icon, screenshots, documentation, featured
compliance instruments[], dataResidency, sovereignty
developer, repository, keywords Kas jį publikuoja ir kur yra jo kodas
metrics, atlas Du sąmoningai atviri objektai jūsų pačių metrikų pavadinimams ir architektūros dokumentacijos generavimui

Ko schema negali išreikšti

JSON Schema nustato formą; definePlugin prideda taisykles, kurių schema negali išreikšti. Įgūdžio classification negali viršyti pasitikėjimo ribos. Tik core ir verified įskiepiai gali deklaruoti tool_using ir llm_only įgūdžius. Kiekvienas deklaruotas kelias turi būti santykinis ir tos pačios kilmės, be schemos, be // ir be atvirkštinio pasvirojo brūkšnio, nes URL analizatorius \ paverčia į /, o /\evil.example/x išsprendžiamas į kitą kilmę. Kiekviena taisyklė, kurią registro sinchronizavimas taiko įgūdžiui, pirmiausia pritaikoma čia, naudojant paties sinchronizavimo kodą, todėl validate ir sinchronizavimas pažeistą taisyklę įvardija vienodai.

Tikrinimas ir perkėlimas iš 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

Klaidos atveju išspausdinamas tikslus kelias, o sinchronizavimo taisyklės atveju – pirmiausia kodas. Paverskite tai commit kabliu.

v1 manifestas perkeliamas mechaniškai. migrate prideda tris įstatymo sakinius, perkelia domain į domains[] ir atsisako sugalvoti įėjimo tašką, kurio neturėjote. Prieš ką nors išspausdindamas ar įrašydamas, jis patikrina rezultatą, todėl migracija niekada neperkelia klaidos iš įrankio į jūsų repozitoriją.

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

Prieš pateikdami pakeitimus (commit) peržiūrėkite skirtumus. Jų pridedami įstatymo sakiniai yra formuluotė, kurią fiksuoja validatorius; savo diegimui nustatykite deploy į anksčiau parodytą sakinį.

Nuomininko aplinkos generavimas ir vaidmenų parūpinimas

Niekada nerašote savo vaidmenų teisių ar eilučių lygio saugumo šablono rankiniu būdu. nexus-tenancy render juos parašo pagal manifesto schema ir db:

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

Sugeneruotas failas sukuria penkis schemos vaidmenis, kiekvienam nurodydamas, ko jis negali turėti: migratorių, kuris gali tik tapti savininku, savininką, kuris negali prisijungti, programos vaidmenį užklausų keliui, ataskaitų vaidmenį, kuris mato tik agregatus, ir žurnalo vaidmenį, kuris gali tik pridėti. Nė vienas vaidmuo neturi BYPASSRLS. Vienintelis būdas susieti nuomininką yra viena duomenų bazės funkcija, o set_config atšaukta visiems vaidmenims, išskyrus savininką.

Pritaikytas nuomos failas niekada neredaguojamas. Pakeitimas yra revizija su savo 0 numerio failu, ir skaitymo vieta tarporganizacinėms teisėms atsiranda būtent taip, kaip 2 revizija. --graph sugeneruoja dvi tipizuoto grafo, kurį deklaruoja jūsų ontology, lenteles kaip kitą sunumeruotą migraciją.

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

Nuomos failas sukuria būtent tuos vaidmenis, kuriais jungiasi vykdyklė, todėl jį taiko duomenų bazės savininkas naudodamas 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> yra duomenų bazės savininko prisijungimo eilutė, o <dir> – privatus katalogas. Parengimas pritaiko bazinį nuomos failą ir visas revizijas iš eilės, įrašo migrator.url ir app.url (ir seat.url, kai yra 2 revizija) į <dir> su režimu 0600 ir neišspausdina nieko slapto. Kiekvieno paleidimo metu jis nustato kiekvieno vaidmens prisijungimų ribą pagal db.maxConnections × db.pods. Pakartotinis paleidimas išlaiko esamus slaptažodžius, nebent paprašysite: --passwords <dir> nustato juos iš failų, o --rotate <roles> suteikia nurodytiems vaidmenims naujus. Paverskite failus savo diegimo paslaptimis.

Po to taikymas jungiasi naudodamas migratoriaus prisijungimo eilutę, kurią įrašė parengimas:

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

Jis vykdo failus nuo 001 kaip migratorius – kiekvieną failą po SET ROLE <schema>_owner, po vieną transakciją kiekvienam failui. Jis tvarko žurnalą <schema>.schema_migrations su kiekvieno failo kontroline suma; pritaikytas failas, kurio baitai pasikeitė, atmetamas nurodant pavadinimą (CHECKSUM_DRIFT), niekada nevykdomas iš naujo ir niekada nepraleidžiamas. Kiekvienas laukiantis failas išanalizuojamas tikrąja Postgres gramatika prieš paleidžiant pirmąjį, todėl atmetimas palieka duomenų bazę nepaliestą. Vienintelė antraštė, kurią gali turėti failas, yra -- nexus-migration: transaction=file|per-statement su neprivalomais užrakto ir sakinio laiko limitais; per-statement skirta CREATE INDEX CONCURRENTLY.

Barjerai

nexus-gates vykdo dvidešimt dvi patikras. Kiekviena užkoduoja vieną defektų klasę, kad ji negalėtų būti išleista du kartus, ir kiekviena turi savitestį, įrodantį, kad ji neišlaiko su tam sukurtu fiktyviu rinkiniu. Paleiskite jas prieš siųsdami pakeitimus:

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test
Patikra Ką ji aptinka
scope-adherence /api maršrutą be prieigos srities apsaugos; anoniminį kelią, kuris nėra tiksliai deklaruotas; įrenginio maršrutą be įrenginio apsaugos arba su asmens apsauga šalia jos
one-fence Nuomininko predikatą, apibrėžtą kur nors kitur nei vienoje vietoje, įskaitant rankomis sukurtą vietos ar teisės užtvarą
sql-fence Sakinį, kuris skaito ar atnaujina apribotą lentelę be užtvaros bet kuriame FROM, JOIN, USING ar UPDATE taikinyje
migrations-are-scoped Lentelę, kurioje trūksta ašies, nuomininku prasidedančio sudėtinio rakto, nuomininką turinčio išorinio rakto ar demonstracinio stulpelio
migrations-commit-what-they-open Migraciją, kurios BEGIN skaičius nesutampa su jos COMMIT ir ROLLBACK skaičiumi
no-direct-compute Tiesioginį modelio teikėjo, variklio, eilės ar darbo eigos serverio iškvietimą; antrą siuntimo URL skaitytoją
no-credentials Modelio teikėjo kredencialą, kurį galima perskaityti repozitorijoje ar aplinkoje
crud-adherence Keičiantį maršrutą, kurio teisės patikra nenurodo nieko registre
blocked-backends Maršrutą, kuris nėra nei aptarnaujamas, nei blokuojamas pagal pavadinimą, nei atmetamas pagal įstatymą, nei priklauso kitur
every-test-runs Testus, kurių testų scenarijaus glob šablonas niekada nepasiekia
tiles-are-invariant Nuo nuomininko nepriklausomą talpykloje saugomą sąsają, kuri skaito nuomininko reikšmę arba praleidžia autentifikavimą
api-contract Užregistruotą maršrutą, kurio manifestas nedeklaruoja, arba deklaruotą, kurio kodas niekada neužregistruoja
rls-present Lentelę be priverstinio eilučių lygio saugumo; SECURITY DEFINER funkciją be fiksuoto search_path
no-set-config Įskiepio kodą, kuris pats susieja nuomininko nustatymą
db-role-honest Užklausos kelią, kuris jungiasi kaip savininkas ar migratorius arba prašo SUPERUSER ar BYPASSRLS
platform-clients SDK klientą, kuris importuotas, bet neįtrauktas į backend.platformClients, arba įtrauktas, bet niekada neimportuotas
rights-register Prieigos srities maršrutą be deklaruotos teisės; teisės patikrą šalia registro
refusal-ledger Deklaruotą atmetimų lentelę be įdiegto žurnalo arba atmetimo turinį, siunčiamą jį apeinant
grants-declared Lentelę su suteiktomis teisėmis, kurios manifestas nedeklaruoja; skaitymo vietos privilegijas, suteiktas rankiniu būdu
people-declared people bloką be jo valymo maršruto, apsaugos ir lentelių
functions-closure Azure Functions įskiepį, kurio aptarnaujami ir deklaruoti maršrutai nesutampa
declared-input Apdorojimo funkcijos užklausos parametrų sąrašą, kuris nesutampa su maršruto deklaruotu query

Kataloge gates/ yra penki išimčių failai, kuriuos patikra gali skaityti (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json ir invariant-seams.json), po vieną priežastį kiekvienam įrašui. Tuščia priežastis laikoma įrašo nebuvimu, o įrašas, nurodantis tai, ko nebėra, neišlaiko patikros. Ten taip pat galite įdėti savo patikrų modulius, ir nexus-gates juos aptiks šalia integruotųjų.

Suderinamumas
Suderinamumas
Suderinamumas rodo, kuri SDK versija veikia su kuria platformos versija, remiantis naktiniais greitosios pradžios vykdymais. Netestuota pora tai nurodo, o neveikianti pora įvardija pakeitimą, kuris ją sugadino.

Šablono konvejeris

Šablone nėra rankomis parašytos darbo eigos. Jo konvejerio konfigūracija nurodo Dockerfile, vienintelį kūrimo argumentą (registro prieigos raktą), bandomąjį migracijos vykdymą ir paleidimo zondą bei patikrą, kurią vykdo suliejimo eilė. Tvarka yra ta, kuria norėtumėte, kad būtų aptinkamos klaidos.

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

Aplink atvaizdą vykdomos dar dvi patikros. Bandomasis migracijos vykdymas pritaiko kiekvieną failą vienkartinei Postgres duomenų bazei, prieš išleidžiant atvaizdą, naudodamas tą pačią vykdyklę kaip ir gamybinė aplinka: nexus-migrate provision vieną kartą kaip supernaudotojas, tada kiekvieną sunumeruotą failą kaip migratorius. Paleidimo zondas paleidžia sukurtą atvaizdą su jo paties įėjimo tašku ir visais kintamaisiais, kuriuos išspausdina required-env, nukreiptais į pakaitalus, kurie priima prisijungimus ir niekada neatsako. Serveris laukia duomenų bazės savo ribotame laiko lange, ir šis laukimas yra sėkmės signalas; konfigūracijos įkėlėjas, kuris atsisako pasileisti, sužlugdo kūrimą čia, o ne gamybinėje aplinkoje.

Kūrimas Community aplinkoje
Kūrimas Community aplinkoje
Naudodamas Community, kūrėjas gauna tuos pačius auksinius kelius, kūrimo erdvę ir duomenų šakas viename serveryje, o kodas laikomas jo paties Git serveryje. Testinė aplinka, bandomieji vienetai ir užmaskuotos tiesioginių duomenų kopijos pateikiamos su Enterprise.

Kiek tai kainuoja

SDK priima sprendimus už jus, ir kai kuriuos iš jų būtumėte priėmę kitaip. Manifestas atmeta jam nežinomus raktus, maršrutų lentelė turi tiksliai atitikti jūsų kodą, duomenų bazės vaidmenų kurti ne jums, o patikros sužlugdo kūrimą dėl trūkstamos teisės skaitymo operacijai. Kurdamas pirmąjį įskiepį, visą dieną ginčijausi su api-contract dėl maršruto, kurį buvau užregistravęs, bet pamiršęs deklaruoti. Jis buvo teisus – maršrutas buvo neapsaugotas. Tikėkitės, kad pirmasis įskiepis atrodys lėtas, o antrasis užtruks trečdalį to laiko.