BejelentkezésBemutató kérése

2.21. fejezet

A Plugin SDK

A Plugin SDK (szoftverfejlesztő készlet) telepítése, parancssori eszközei, a teljes körű szolgáltatási sablon bemutatása, a v2 manifesztum mezőről mezőre, valamint a huszonkét kapu, amely betartatja a szabályokat a beépülő modullal.

Ezt az oldalt AI fordította az eredeti angol szövegből. Ha bármi nem egyértelmű, az angol nyelvű oldal az irányadó. Oldal olvasása angolul

22 perc olvasási idő

A második pluginom harmadannyi idő alatt készült el, mint az első, és a megtakarítás szinte teljes egészében az SDK-nak (szoftverfejlesztői készletnek) volt köszönhető. Első alkalommal írtam egy hatókör-ellenőrzést, egy konfigurációbetöltőt és egy migrációfuttatót, és a bíráló mindegyiket visszaküldte. Második alkalommal egyetlen vázgeneráló parancsot futtattam, töröltem a minta hangulatelemző skillt, és a napjaimat azokra az anomália-felülvizsgálati rekordokra fordítottam, amelyekre a repülésdinamikai csapatunknak ténylegesen szüksége volt.

A @adverant-nexus/plugin-sdk egyetlen npm-csomag. Tartalmazza a v2 manifest sémáját és az azt olvasó validátorokat (definePlugin, defineSkill), azokat a futásidejű modulokat, amelyeket a pluginja a hatókörhöz, az adatbázishoz, a diszpécseléshez és a többihez importál, a teszt-segédeszközöket, a megfelelőségi kapukat és a parancssori eszközöket. Ez a fejezet a telepítést, az eszközöket, a sablont, a manifestet és a kapukat tárgyalja. A futó kódban használt futásidejű modulokat a 2.22. fejezet, A plugin futtatókörnyezete tárgyalja.

Telepítés

A csomag az Adverant https://registry.adverant.ai/npm/ címen elérhető registryjéből származik, soha nem a nyilvános npm registryből, és szüksége van a fiókja „Pull tokens and install commands” oldalán található pull tokenre. Állítsa a @adverant-nexus hatókört a registryre a repository .npmrc fájljában:

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

A <pull-token> a fiókoldaláról származó token. Pipeline-ban titokból adja át, és soha ne commitolja; a sablon Dockerfile-ja nélküle megtagadja a buildet, és a npm ci lefutása után törli a .npmrc fájlt a build szakaszból, így a token soha nem kerül bele image-be.

Ezután rögzítse pontosan a verziót:

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

Az első telepítéskor commitolja a package-lock.json fájlt. A sablon image-buildje a npm ci parancsot futtatja, és megtagadja a npm install parancsra való visszalépést: a lockfile a szerződés. Az SDK minimális követelménye a Node 18; a sablon a Node 20-at célozza.

A parancssori eszközök a csomagon belül érkeznek, ezért a dokumentáció minden parancsa a npx -p használatával megnevezi a csomagot és annak verzióját. Önmagában a npx create-nexus-plugin a nyilvános registryben kerül keresésre, és az a név nem ez a csomag.

A parancssori eszközök

Eszköz Mit csinál
create-nexus-plugin Pluginvázat generál, manifestet validál, v1 manifestet migrál v2-re, és elkészíti a fogyasztói útmutatót a frontendfejlesztője számára
nexus-tenancy A manifestből előállítja a séma bérlőkezelési SQL-jét: szerepköröket, jogosultságokat, a sorszintű biztonsági sablont és a gráftáblákat
nexus-migrate Alkalmazza a migrációkat: egyszer létrehozza a szerepköröket, majd migrátor szerepkörként lefuttatja az egyes számozott fájlokat
nexus-gates Lefuttatja az összes megfelelőségi kaput és az egyes kapuk saját önellenőrzését

A create-nexus-plugin nem indít hálózati hívást, és nem tölt be távoli kódot. Ugyanazokat a folyamaton belüli validátorokat futtatja, mint a platform bevezetési folyamata, így nincs eltérés a „nálam validált” és a „a platform elfogadta” között.

Művelet Kapcsolók Mit csinál Kilépési kódok
scaffold <name> --tier full-service\|ui-only\|skills-only, --dir <path>, --print Új pluginkönyvtárat ír; a --print csak a manifestet írja ki 0 megírva · 1 felülírás megtagadva · 2 hibás használat
validate <file> Validál egy nexus.manifest.json fájlt, vagy egy ilyet exportáló .ts vagy .js modult 0 érvényes · 1 érvénytelen vagy olvashatatlan · 2 hibás használat
migrate <file> --write Egy v1 manifestet v2-re emel, és kiírja vagy helyben felülírja 0 · 1 · 2, mint fent
guide --manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint Elkészíti a fogyasztói útmutatót a manifestből és az Ön leírásából; a --check összeveti a commitolt példánnyal, és semmit nem ír 0 · 1 eltérés vagy lint-szabálysértés · 2 hibás használat
help Kiírja a használati útmutatót 0

Alapstruktúra-generálás (scaffolding) és a három szint

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

A --tier alapértéke full-service. A vázgenerátor megtagadja az írást létező könyvtárba, és az általa írt manifest már átmegy a validáláson; soha nem hoz létre érvénytelent.

A szintet aszerint válassza, hogy mi van a pluginjában.

Szint Tartalmaz Kötelezően deklarálandó
skills-only Csak manifest skilleket skills[], legalább egy bejegyzéssel
ui-only Frontendfelületet a shellen belül frontend
full-service Backendet és frontendet, általában saját sémával backend és frontend; és mivel backendje van, runtime.healthCheck

Ha bizonytalan, generálja a full-service vázat, és törölje, amire nincs szüksége. A másik irány azt jelenti, hogy meg kell írnia azokat a részeket, amelyeket a sablon megadott volna.

A teljes körű szolgáltatási sablon bemutatása

A sablon a referenciaplugin, amely a későbbi fejezetek által feltételezett szigorú mintára épül. Az alakját másolja le, ne a mintalogikáját.

Elérési út Mi ez
nexus.manifest.json A v2 manifest: a három törvény újrafogalmazva, az útvonaltábla és a jogosultság-nyilvántartása
src/config.ts A konfigurációbetöltő. Egy specifikáció, egyszer beolvasva, minden hiba összegyűjtve, mielőtt a folyamat megtagadja az indulást
src/scope.ts Az egyetlen fájl, amely a kérésből hatókört képez, az SDK szigorú tokenellenőrzőjével és két renddel: egy személy bearer tokenjével és a platform szolgáltatáshívásával
src/db.ts Minden utasítás a tenantFence() használatával épül fel, és a withScopedTx belül fut
src/uno.ts Az egyetlen diszpécserfájl: egy URL, egy kliens, zárt engedélyezési lista
src/routes/*.ts health (névtelen, pontos útvonal), a /api útvonalak (hatókörhöz kötött) és a /internal visszahívás (szolgáltatásvédett)
src/skills/sentiment.ts Determinisztikus host_callback skill; cserélje le a szótárat a saját logikájára
src/server.ts A kompozíciós gyökér: egyszer telepíti az elutasítási naplót, (korlátozott ideig) vár az adatbázisra, majd a figyelés megkezdése előtt lefuttatja az izolációs és naplóellenőrzéseket
migrations/000_tenancy.sql A nexus-tenancy render állítja elő a vázgeneráláskor: szerepkörök, séma, a sorszintű biztonsági sablon
migrations/001_init.sql Két tábla bérlővel kezdődő összetett kulccsal és összetett, bérlőt hordozó idegen kulccsal
migrations/002_refusal_ledger.sql Az a tábla, amelybe az elutasítási napló ír
scripts/ci/required-env JSON formátumban kiírja az indításhoz szükséges környezeti változók neveit
scripts/ci/shadow-migrate-*.sh A pipeline migrációs próbafuttatása a nexus-migrate használatával
gates/ A kapuk mentességi könyvtára: üres, ami egy új plugin helyes állapota
test/ Tesztek a hatókörhöz, az útvonalakhoz, az adatbázishoz, a diszpécseléshez és az indításhoz, azokkal a hatókör-helyettesítőkkel, amelyeket minden teszt injektál
Dockerfile Nem root image (felhasználói azonosító: 10001), benne a migrációkkal

Néhány fájlt érdemes közelebbről is megvizsgálni.

A src/config.ts két szabályt követ. Minden hibát összegyűjt, mielőtt kivételt dob, így egyetlen újraindítás megnevezi mind az öt hiányzó változót ahelyett, hogy öt újraindítás nevezne meg egyet-egyet. Továbbá csak akkor ad alapértéket, ha egy hibás érték nem vezethet csendes, hibás eredményhez: a PORT alapértéke lehet 8080, mert a hibás port láthatóan meghiúsítja a kötést, míg a DATABASE_URL és a UNO_DISPATCH_URL kötelező, és fürtön belüli címnek kell lennie. A nyilvános címet az indításkor elutasítja.

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

A sablon saját tesztje lefuttatja ezt a fájlt, és összeveti a kimenetét azokkal a nevekkel, amelyeket a konfigurációs specifikáció kötelezőként jelöl, így ha egy kötelező változót a lista frissítése nélkül vesz fel, a npm test sikertelen lesz.

A src/server.ts addig nem kezd figyelni, amíg az adatbázis nem válaszol, és a várakozást 120 másodpercre korlátozza, minden sikertelen kísérletet az okával együtt naplózva. Ezután sorrendben igazolja, hogy az alkalmazás szerepköre nem tudja újrakötni a bérlőt, és minden tábla kényszerítetten sorszintű biztonság alatt áll, hogy minden pod készlete belefér a szerepkör kapcsolatkorlátjába, és hogy az elutasítási napló táblája képes sort fogadni. A három bármelyikének elutasítása teljes egészében kiírásra kerül, és a folyamat 2-es kóddal kilép.

A v2 manifesztum, mezőről mezőre

A manifest a plugin géppel olvasható szerződése a platformmal. Validálásra kerül, amikor Ön megírja, amikor a platform bevezeti, és azt követően folyamatosan. A séma minden szinten additionalProperties: false: ha a pluginjának van egy szakasza, létezik hozzá tulajdonság, a nem deklarált kulcsot pedig elutasítja. A megoldás mindig a megfelelő opcionális tulajdonság használata.

A kötelező mag

Mező Szabály
manifestVersion Pontosan "2". A v1 dokumentum migrálásra kerül, soha nem validálódik újra helyben
name ^[a-z0-9]+([-.][a-z0-9]+)*$, legfeljebb 64 karakter. A regisztrációban, a diszpécselési névtérképzésben és a bérlőhöz kötött sorokban használt pluginazonosító. A skilleket deklaráló pluginnak olyan névre is szüksége van, amely nem tartalmaz pontot, és nem kezdődik számjeggyel
displayName 1–120 karakter
version Szemantikus verzió; az Ön saját kiadási ütemezése
description, author, license Mindegyik legalább egy karakter
tier skills-only, ui-only vagy full-service
trust core, verified, community vagy untrusted
runtime Kötelező: executionMode, isolationLevel (1–4), entrypoint. Opcionális: nodeVersion, healthCheck, readinessCheck, livenessCheck, mindegyik / kezdetű útvonal. A mód a szintből adódik: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker
architecture compute, ai és deploy, a három platformtörvény újrafogalmazva. A validátor rögzíti a megfogalmazást

A saját telepítéséhez készített plugin esetében a három mondat a következőképpen hangzik. A ai mondat a mesterséges intelligenciára (AI) vonatkozik, és itt kell kijelenteni, hogy a plugin nem tárol modell-hitelesítő adatokat.

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

Az útvonaltábla: api és rights

A api megköveteli a version és a basePath mezőt, opcionálisan a websocket (path, auth) és a endpoints[] mezőt is. Az útvonaltábla a séma legerősebb gondolata: egy kapu mindkét irányban összeveti azokkal az útvonalakkal, amelyeket a kódja ténylegesen regisztrál, így a manifest ellenőrizhető szerződés, nem pedig dokumentáció.

Minden végpontnak szüksége van a method (GET, POST, PUT, PATCH vagy DELETE) és a path mezőre. A többi:

Mező Mit tartalmaz
auth Öt osztály egyike: scope (egy személy útvonala, a hatókörvédő mögött), service-key és internal (szerver–szerver, böngészőből soha nem érhető el), public (mindig csak pontos útvonal a allowAnonymous mellett) és device (saját hitelesítő adattal rendelkező gép, az eszközvédő mögött)
right Kötelező minden olyan útvonalon, amelyet a hatókörvédő szolgál ki, és minden másikon elutasított: a rights nyilvántartásban szereplő jogosultság neve
needsUnit Az útvonal elutasít, ha a hívó egysége nem oldható fel
allowAnonymous Csak pontos egyezésű engedélyezési lista. Egy előtagszabály miatt válik a /health-of-tenant-42 nyilvánossá
group, serves, screens Egy release blokkon belül: az útvonal által kiszolgált képességcsoport, az, amit akkor válaszol, ha a csoport licencelt funkciója zárolva van (data, teaser, sighting vagy ask), valamint az általa kiszolgált képernyők
query required (mindegyik név egy példaértékkel) és allowed: az útvonal által olvasott lekérdezési paraméterek
body example: egy író útvonal példatörzse, amelyet a saját validátora elfogad. GET esetén soha

A rights az a nyilvántartás, amelyre ezek az útvonalak hivatkoznak. Minden jogosultságnak van roles mezője (a felső határ), és opcionálisan summary, never (azok a szerepkörök, amelyek soha nem gyakorolhatják, bármi mással rendelkeznek is), barred (a termék saját megfogalmazása egy never szerepkör elutasítására), seat (élő licenchely is szükséges), self (minden ellenőrzött személy rendelkezik vele, a saját munkamenetük feletti jogosultságokhoz), grants (a birtokosai licenchelyeket osztanak ki; legfeljebb egy jogosultság mondhatja ezt), licence (olyan licencelt funkció, amelyet a szervezet licencének tartalmaznia kell), installation (csak a telepítés saját adminisztrátorai rendelkeznek vele) és platform (csak az Adverant platformadminisztrátorai rendelkeznek vele; szerepköröket nem nevez meg). A jogosultságnevek legalább egy pontot tartalmaznak: 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"] }
}

A definePlugin elutasítja a jogosultság nélküli hatókör-útvonalat (ENDPOINT_RIGHT_MISSING), a nyilvántartásban nem szereplő jogosultságot (ENDPOINT_RIGHT_NOT_REGISTERED), valamint az olyan útvonalon lévő jogosultságot, amelyet egyetlen védő sem szolgál ki (ENDPOINT_RIGHT_UNGUARDED). Elutasítja az önellentmondó nyilvántartást is, valamint egy útvonal két írásmódját (:id és :recordId) DUPLICATE_ENDPOINT hibaként.

Az Ön adatai: databases, schema és db

A schema az egyetlen Postgres-séma, amely a pluginé. A public, plugins, auth és nexus tiltott, és ha a databases[] is megnevez egy Postgres-sémát, a kettőnek egyeznie kell.

A databases[] motoronként deklarálja az egyes tárolókat: postgresql (schema, tables, migrations és granted, azok a táblák, amelyeket egy másik szervezet rögzített engedély alapján olvashat), neo4j (schemas), qdrant (collections) vagy redis (purpose).

A db tartalmazza a plugin által megnyitott összes kapcsolat munkamenet-korlátait, amelyeket itt deklarálnak, nem pedig kódban, hogy a bíráló és a telepítés egyaránt olvashassa őket:

Mező Mit korlátoz
maxConnections A replikánkénti készletet
pods Az egyszerre készletet tartó podok maximális számát, a replikák és a gördülő frissítés túllépésének összegét. Az egyes szerepkörök kapcsolatkorlátja maxConnections × pods formában jelenik meg; ha elhagyja, a definePlugin figyelmeztet: DB_PODS_UNDECLARED
statementTimeoutMs Egy utasítást
idleInTransactionTimeoutMs Egy nyitott, semmit nem futtató tranzakciót
workMemKB Egy rendező vagy hash csomópontot, csomópontonként, nem lekérdezésenként
piiMask[] Személyes adatokat tartalmazó table.column bejegyzések, amelyek maszkolva jelennek meg a szabályozott SQL-konzolban és a naplókban

Skillek és eszközök: skills, mcpTools, entitlements

A skills[] a manifest skilleket tartalmazza; mezőiket és szintjeiket a 2.20. fejezet, Skillek tárgyalja. A mcpTools[] a plugin által közzétett MCP- (Model Context Protocol) eszközöket tartalmazza, mindegyik egy name, egy description és egy inputSchema, legfelső szintű oneOf, allOf vagy anyOf nélkül.

A entitlements megköveteli a featureIdPattern mezőt, és elfogadja a alwaysOn[], source és store mezőt. A minta azt a névteret nevezi meg, amelyben a funkcióazonosítók élnek, megállapodás szerint a plugin name értékét és egy további szegmenst, amelyet a kódja felületenként tölt ki. A alwaysOn[] az a rövid, pontos lista, amelynek akkor is válaszolnia kell, ha nem kapható jogosultsági döntés: állapot, készenlét, bejelentkezés, valamint azok a beállítások, amelyekre egy adminisztrátornak a jogosultság helyreállításához szüksége van.

Változáskezelés: changePolicy

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

A jóváhagyásokat különböző személyek szerint számolják, és a változtatást javasló személy soha nem tartozik közéjük; e két feltétel nélkül a „két jóváhagyás” egyetlen személy kétszeri kattintásává válik. A enabled: true megköveteli a classes mezőt, és minden megnevezett osztálynak saját darabszám kell. Az elhagyott osztály szabályozatlan, ami jogos választás, de a séma megköveteli, hogy ezt írásban rögzítse.

Kicsoda Ön: domains, branding, routing

A domains[] (mindegyik primary és aliases[]; a domain az egytartományos forma) felsorolja, hol válaszol a plugin. A branding megköveteli a appName mezőt, és elfogadja a tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId és gaId mezőt. A branding tartalma teljes egészében nyilvános: a bejelentkezési oldal azelőtt olvassa, hogy bárkinek hitelesítő adata lenne, ezért soha nem tartalmazhat titkot vagy belső címet. A routing (type, gateway, virtualService) azoknak a pluginoknak szól, amelyek saját útválasztásukat írják le.

Méretezés és egyebek

A(z) resources megköveteli a(z) cpuMillicores (10 és 64 000 között) és a(z) memoryMB (16 és 262 144 között) mezőt, és elfogadja a(z) diskGB, timeoutMs, port és wsPort mezőt. A(z) backend tartalmazza a(z) port, healthPath, apiPrefix, framework és platformClients[] elemet, azokat az SDK-klienseket, amelyeket a háttérrendszere név szerint importál. A lista zárt, és egy ellenőrzőkapu összeveti az Ön importjaival. A séma tizennégy nevet enged meg: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin és uno, továbbá egyet annak a kliensnek, amely a csomagjogosultsági elutasításokra válaszol, és amely belső nevet visel. A funkciójogosultsági kliens, a(z) runtime/entitlements, nem tartozik közéjük, és soha nem kerül fel a listára, mert az Ön entitlements blokkja már deklarálja, és az a háttérrendszer, amely entitlements blokk nélkül importálja, ugyanazon az ellenőrzőkapun bukik el. A(z) frontend tartalmazza a(z) basePath, mountPath és framework elemet. A(z) nexus tartalmazza a(z) minVersion, maxVersion, capabilities[] és permissions[] elemet.

A többi blokk mindegyike egyetlen feladatot szolgál:

Blokk Célja
settings Az Ön beállításai a közös keretrendszeren: groups és keys, az egyes beállítások által megnevezett szinteken megadva
people sweep (service, port): a szervezet tagjai, az identitásszolgáltatásból szinkronizálva, a helyek kikapcsolásával, amikor valaki távozik
ontology entityTypes és relationshipTypes: a típusos gráf, amelyet a saját sémájában tárol
release groups és frame: azok a képességcsoportok, amelyekben az útvonalai fokozatosan kerülnek bevezetésre, elsőként canary kiadásként
cells[] Több telepíthető egységből álló bővítmény: mindegyikhez name, kind, entrypoint, port, wsPort
pricing model, currency, tiers[] a katalógusbeli listázásához
marketplace category, icon, screenshots, documentation, featured
compliance instruments[], dataResidency, sovereignty
developer, repository, keywords Ki teszi közzé, és hol található a kódja
metrics, atlas A két szándékosan nyitott objektum, a saját metrikaneveihez és az architektúra-dokumentáció generálásához

Amit a séma nem tud kifejezni

A JSON Schema a szerkezetet rögzíti; a(z) definePlugin hozzáadja azokat a szabályokat, amelyeket egy séma nem tud kifejezni. Egy képesség classification értéke nem haladhatja meg a bizalmi felső határt. Csak core és verified bővítmények deklarálhatnak tool_using és llm_only képességeket. Minden deklarált útvonalnak relatívnak és azonos eredetűnek kell lennie, séma, // és fordított perjel nélkül, mert az URL-elemző a(z) \ karaktert / karakterré alakítja, és a(z) /\evil.example/x más eredetre oldódik fel. Minden szabályt, amelyet a regisztrációs szinkronizálás egy képességre alkalmaz, előbb itt alkalmazunk, a szinkronizálás saját kódjával, így a(z) validate és a szinkronizálás ugyanúgy nevezi meg a megsértett szabályt.

Validálás és átállás v1-ről

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

Hiba esetén pontos útvonalat ír ki, szinkronizálási szabály esetén pedig elsőként a kódot. Állítsa be commit hookként.

Egy v1 manifest gépiesen átemelhető. A(z) migrate hozzáadja a három jogi mondatot, a(z) domain elemet a(z) domains[] helyre mozgatja, és nem hajlandó olyan belépési pontot kitalálni, amely korábban nem létezett. Az eredményt kiírás vagy mentés előtt validálja, így a migráció soha nem helyez át egy hibát az eszközből az Ön tárolójába.

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

Olvassa el a diffet, mielőtt véglegesíti. Az általa hozzáadott jogi mondatok a validátor által rögzített megfogalmazást követik; saját telepítéséhez állítsa a(z) deploy értékét a korábban bemutatott mondatra.

A bérlői környezet (tenancy) kirenderelése és a szerepkörök kiosztása

A szerepkör-jogosultságokat és a sorszintű biztonsági sablont soha nem kell kézzel megírnia. A(z) nexus-tenancy render a manifest schema és db eleméből állítja elő őket:

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

Az előállított fájl öt szerepkört hoz létre a sémához, mindegyiket azzal együtt, amivel nem rendelkezhet: egy migrátort, amely csak tulajdonossá válhat, egy tulajdonost, amely nem tud bejelentkezni, egy alkalmazásszerepkört a kérések útvonalához, egy jelentésszerepkört, amely csak összesítéseket lát, és egy főkönyvi szerepkört, amely csak hozzáfűzni tud. Egyik szerepkör sem rendelkezik BYPASSRLS jogosultsággal. Bérlőt kizárólag egyetlen adatbázisfüggvénnyel lehet kötni, és a(z) set_config jogosultság a tulajdonos kivételével minden szerepkörtől vissza van vonva.

Egy már alkalmazott bérlői fájlt soha nem szerkesztünk. A módosítás egy revízió, saját 0-s számú fájllal, és a szervezetek közötti jogosultságokhoz tartozó olvasási hely is így érkezik, 2. revízióként. A(z) --graph a(z) ontology által deklarált típusos gráf két tábláját a következő sorszámozott migrációként állítja elő.

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

A bérlői fájl éppen azokat a szerepköröket hozza létre, amelyekként a futtató csatlakozik, ezért az adatbázis tulajdonosa alkalmazza a(z) nexus-migrate provision paranccsal:

DATABASE_URL=<database-owner-url> npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate provision --state <dir>

A(z) <database-owner-url> az adatbázis tulajdonosának kapcsolati karakterlánca, a(z) <dir> pedig egy privát könyvtár. A provisioning sorrendben alkalmazza az alap bérlői fájlt és minden revíziót, a(z) migrator.url és app.url fájlt (valamint a(z) seat.url fájlt, ha a 2. revízió létezik) 0600 jogosultsággal a(z) <dir> könyvtárba írja, és semmilyen titkos adatot nem ír ki. Minden futtatáskor beállítja az egyes szerepkörök kapcsolati korlátját a(z) db.maxConnections × db.pods alapján. Ismételt futtatáskor a meglévő jelszavak megmaradnak, hacsak másként nem kéri: a(z) --passwords <dir> fájlokból állítja be őket, a(z) --rotate <roles> pedig új jelszót ad a megnevezett szerepköröknek. Alakítsa a fájlokat a telepítése titkaivá.

Ezt követően az alkalmazás a migrátor azon kapcsolati karakterláncával csatlakozik, amelyet a provisioning kiírt:

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

A 001-es fájltól kezdve migrátorként futtatja a(z) SET ROLE <schema>_owner alatti összes fájlt, fájlonként egy tranzakcióban. Főkönyvet vezet, a(z) <schema>.schema_migrations táblát, minden fájl ellenőrzőösszegével; egy már alkalmazott fájlt, amelynek bájtjai megváltoztak, név szerint elutasít (CHECKSUM_DRIFT), soha nem futtat újra és soha nem hagy ki. Minden függőben lévő fájlt a valódi Postgres-nyelvtannal elemez, mielőtt az első lefutna, így elutasítás esetén az adatbázis érintetlen marad. Egy fájl egyetlen fejlécet tartalmazhat, a(z) -- nexus-migration: transaction=file|per-statement fejlécet, opcionális zárolási és utasítás-időkorlátokkal; a(z) per-statement a(z) CREATE INDEX CONCURRENTLY számára szolgál.

A kapuk

A(z) nexus-gates huszonkét ellenőrzőkaput futtat. Mindegyik a hibák egy osztályát rögzíti, hogy az ne kerülhessen ki kétszer, és mindegyikhez tartozik egy önteszt, amely igazolja, hogy elbukik egy kifejezetten erre készített teszt-adatkészleten. Futtassa őket, mielőtt push műveletet végez:

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test
Ellenőrzőkapu Mit szűr ki
scope-adherence /api útvonal hatókörvédelem nélkül; névtelen útvonal, amely nem pontosan egy deklarált útvonal; eszközútvonal eszközvédelem nélkül, vagy mellette egy személyre vonatkozó védelemmel
one-fence Bérlői predikátum, amely nem az egyetlen kijelölt helyen van definiálva, beleértve a kézzel írt hely- vagy jogosultsági korlátot is
sql-fence Olyan utasítás, amely hatókörhöz kötött táblát olvas vagy frissít a korlát nélkül, bármely FROM, JOIN, USING vagy UPDATE célban
migrations-are-scoped Olyan tábla, amelyből hiányzik egy tengely, egy bérlővel kezdődő összetett kulcs, egy bérlőt hordozó idegen kulcs vagy a demóoszlop
migrations-commit-what-they-open Olyan migráció, amelynek BEGIN száma nem egyezik a(z) COMMIT és ROLLBACK számával
no-direct-compute Modellszolgáltató, motor, sor vagy munkafolyamat-gazda közvetlen hívása; a diszpécser-URL második olvasója
no-credentials A tárolóban vagy a környezetben olvasható modellszolgáltatói hitelesítő adat
crud-adherence Módosító útvonal, amelynek jogosultság-ellenőrzése semmit sem nevez meg a nyilvántartásból
blocked-backends Olyan útvonal, amelyet sem nem szolgálnak ki, sem nem tiltanak le név szerint, sem nem utasít el jogszabály, sem nem birtokol más
every-test-runs Tesztek, amelyeket a tesztszkript globmintája soha nem ér el
tiles-are-invariant Bérlőfüggetlen, gyorsítótárazott csatlakozási pont, amely bérlői értéket olvas vagy kihagyja a hitelesítést
api-contract Regisztrált útvonal, amelyet a manifest nem deklarál, vagy deklarált útvonal, amelyet a kód soha nem regisztrál
rls-present Kényszerített sorszintű biztonság nélküli tábla; SECURITY DEFINER függvény rögzített search_path nélkül
no-set-config Bővítménykód, amely maga köti a bérlői beállítást
db-role-honest Kérési útvonal, amely tulajdonosként vagy migrátorként csatlakozik, vagy SUPERUSER vagy BYPASSRLS jogosultságot kér
platform-clients SDK-kliens, amely importálva van, de nem szerepel a(z) backend.platformClients listában, vagy szerepel, de soha nincs importálva
rights-register Hatóköri útvonal deklarált jogosultság nélkül; jogosultság-ellenőrzés a nyilvántartás mellett
refusal-ledger Deklarált elutasítási tábla telepített főkönyv nélkül, vagy azt megkerülve küldött elutasítási törzs
grants-declared Jogosultsággal ellátott tábla, amelyet a manifest nem deklarál; kézzel kiosztott olvasásihely-jogosultságok
people-declared people blokk a hozzá tartozó takarítási útvonal, védelem és táblák nélkül
functions-closure Azure Functions-bővítmény, amelynek kiszolgált és deklarált útvonalai eltérnek
declared-input Kezelő, amelynek lekérdezésiparaméter-listája nem egyezik az útvonal deklarált query értékével

A(z) gates/ könyvtár tartalmazza azt az öt kivételfájlt, amelyet egy ellenőrzőkapu olvashat (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json és invariant-seams.json), bejegyzésenként egy indoklással. Az üres indoklás bejegyzés hiányának számít, és az a bejegyzés, amely már nem létező elemet nevez meg, az ellenőrzőkapu bukását okozza. Saját ellenőrzőkapu-moduljait is elhelyezheti itt, és a(z) nexus-gates a beépítettek mellett ezeket is felismeri.

Kompatibilitás
Kompatibilitás
A Kompatibilitás oldal a gyorsindítás éjszakai futtatásai alapján mutatja, hogy melyik SDK-verzió melyik platformverzióval működik. A nem tesztelt párosításoknál ez fel van tüntetve, a hibás párosításoknál pedig meg van nevezve az a változás, amely a hibát okozta.

A sablon CI/CD folyamata (pipeline)

A sablon nem tartalmaz kézzel írt munkafolyamatot. A folyamatkonfigurációja megnevezi a Dockerfile-t, az egyetlen buildargumentumot (a registry tokent), a migrációs próbafuttatást és az indítási próbát, valamint az ellenőrzőkaput, amelyet az egyesítési sor futtat. A sorrend az, amelyben a hibákat észlelni szeretné.

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

Az image körül további két ellenőrzés fut. A migrációs próbafuttatás minden fájlt alkalmaz egy eldobható Postgres-példányon, mielőtt az image kiadható lenne, ugyanazzal a futtatóval, amelyet az éles környezet is használ: a(z) nexus-migrate provision parancsot egyszer superuserként futtatja, majd minden sorszámozott fájlt migrátorként alkalmaz. Az indítási próba a saját belépési pontjával indítja el az elkészült image-et, minden olyan változóval, amelyet a(z) required-env kiír, olyan helyettesítőkre irányítva, amelyek elfogadják a kapcsolatokat, de soha nem válaszolnak. A szerver a korlátozott időablakán belül vár az adatbázisra, és ez a várakozás a sikeresség jele; az a konfigurációbetöltő, amely nem hajlandó elindulni, ott bukja el a buildet, nem pedig éles környezetben.

Fejlesztés a Community kiadáson
Fejlesztés a Community kiadáson
A Community kiadásban a fejlesztők ugyanazokat a bevált útvonalakat, egy fejlesztői teret és adatágakat kapnak egyetlen szerveren, a kódot pedig saját Git-szolgáltatójukon tárolják. Az előéles környezet, a pilot egységek és az éles adatok maszkolt másolatai az Enterprise kiadással érhetők el.

Mennyibe kerül

Az SDK döntéseket vesz el Öntől, és ezek közül néhányat Ön másként hozott volna meg. A manifest elutasítja az ismeretlen kulcsokat, az útvonaltáblának pontosan egyeznie kell a kóddal, az adatbázis-szerepkörök megtervezése nem az Ön feladata, és az ellenőrzőkapuk egy olvasási művelethez hiányzó jogosultság miatt is elbuktatják a buildet. Az első bővítményemnél egy napot vitatkoztam a(z) api-contract eszközzel egy útvonal miatt, amelyet regisztráltam, de elfelejtettem deklarálni. Neki volt igaza: az útvonal védelem nélkül maradt. Számítson arra, hogy az első bővítmény lassúnak tűnik majd, és arra, hogy a második harmannyi időt vesz igénybe.