Prihlásiť saRezervovať brífing

Kapitola 2.21

Plugin SDK

Inštalácia sady Plugin SDK (sada nástrojov na vývoj softvéru), jej nástroje príkazového riadka, prehliadka šablóny plnohodnotnej služby, manifest v2 pole po poli a dvadsaťdva brán, ktoré dohliadajú na to, aby zásuvný modul dodržiaval pravidlá.

Táto stránka bola preložená pomocou AI z anglického originálu. V prípade akýchkoľvek nejasností je rozhodujúca anglická verzia stránky. Prečítať túto stránku v angličtine

22 min čítania

Môj druhý zásuvný modul mi zabral tretinu času oproti prvému a takmer celú túto úsporu priniesla súprava SDK (software development kit). Prvýkrát som napísal kontrolu rozsahu (scope check), zavádzač konfigurácie a spúšťač migrácií a revízor mi každý jeden z nich vrátil späť. Druhýkrát som spustil jeden príkaz na vygenerovanie kostry (scaffold), odstránil ukážkovú zručnosť na analýzu sentimentu a celé dni som venoval záznamom o revízii anomálií, ktoré náš tím letovej dynamiky skutočne potreboval.

@adverant-nexus/plugin-sdk je jeden balík npm. Obsahuje schému manifestu v2 a validátory, ktoré ju čítajú (definePlugin, defineSkill), behové moduly (runtime modules), ktoré váš zásuvný modul importuje pre rozsah (scope), databázu, odosielanie (dispatch) a zvyšok, pomocné nástroje pre testy, kontrolné brány dodržiavania pravidiel (adherence gates) a nástroje príkazového riadka. Táto kapitola sa venuje jeho inštalácii, nástrojom, šablóne, manifestu a kontrolným bránam. Kapitola 2.22, Behové prostredie zásuvného modulu, sa venuje behovým modulom vo vašom spustenom kóde.

Inštalácia

Balík pochádza z registra spoločnosti Adverant na adrese https://registry.adverant.ai/npm/, nikdy nie z verejného registra npm, a potrebujete token na sťahovanie (pull token) zo stránky „Pull tokens and install commands“ vášho účtu. Nasmerujte rozsah @adverant-nexus na register v súbore .npmrc vášho repozitára:

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

<pull-token> je token zo stránky vášho účtu. V pipeline ho odovzdajte z tajného úložiska (secret) a nikdy ho neodošlite do repozitára (commit); Dockerfile šablóny sa bez neho odmietne zostaviť a po dobehnutí npm ci odstráni .npmrc z fázy zostavenia, takže token sa nikdy nedostane do obrazu (image).

Potom presne zafixujte verziu:

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

Pri prvej inštalácii odošlite package-lock.json do repozitára (commit). Zostavenie obrazu šablóny spúšťa npm ci a odmieta sa prepnúť späť na npm install: súbor zámku (lockfile) je zmluva. Samotné minimum súpravy SDK je Node 18; šablóna cieli na Node 20.

Nástroje príkazového riadka sa dodávajú vo vnútri balíka, takže každý príkaz v tejto dokumentácii uvádza názov balíka a jeho verziu pomocou npx -p. Samotný príkaz npx create-nexus-plugin sa vyhľadáva vo verejnom registri a tento názov nepatrí tomuto balíku.

Nástroje príkazového riadka

Nástroj Čo robí
create-nexus-plugin Vygeneruje kostru zásuvného modulu, zvaliduje manifest, zmigruje manifest v1 na v2 a vygeneruje príručku spotrebiteľa pre vášho frontendového vývojára
nexus-tenancy Vygeneruje SQL pre viacnásobný prenájom (tenancy) vašej schémy z manifestu: roly, oprávnenia (grants), šablónu zabezpečenia na úrovni riadkov (RLS) a grafové tabuľky
nexus-migrate Aplikuje vaše migrácie: raz zriadi roly a potom spustí každý očíslovaný súbor pod rolou migrátora
nexus-gates Spustí každú kontrolnú bránu dodržiavania pravidiel a vlastný autotest každej brány

create-nexus-plugin nevykonáva žiadne sieťové volania a nenačítava žiadny vzdialený kód. Spúšťa tie isté interné validátory procesu, ktoré spúšťa aj proces nasadenia (onboarding) platformy, takže nedochádza k žiadnemu posunu medzi „zvalidovalo sa to na mojom stroji“ a „platforma to prijala“.

Príkaz Príznaky Čo robí Návratové kódy
scaffold <name> --tier full-service\|ui-only\|skills-only, --dir <path>, --print Zapíše nový adresár zásuvného modulu; --print vypíše iba manifest 0 zapísané · 1 odmietnuté prepísanie · 2 nesprávne použitie
validate <file> Zvaliduje nexus.manifest.json, prípadne modul .ts alebo .js, ktorý ho exportuje 0 platné · 1 neplatné alebo nečitateľné · 2 nesprávne použitie
migrate <file> --write Povýši manifest v1 na v2 a vypíše ho, alebo ho zapíše na pôvodné miesto 0 · 1 · 2, ako je uvedené vyššie
guide --manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint Vygeneruje príručku spotrebiteľa z manifestu a vášho sprievodného textu; --check ju porovná s verziou odoslanou v repozitári a nič nezapíše 0 · 1 odchýlka alebo porušenie pravidiel linteru · 2 nesprávne použitie
help Vypíše návod na použitie 0

Príprava kostry (scaffolding) a tri úrovne

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

--tier má predvolenú hodnotu full-service. Nástroj na generovanie kostry odmietne zapisovať do adresára, ktorý už existuje, a manifest, ktorý zapíše, už prechádza validáciou; nikdy nevygeneruje neplatný manifest.

Vyberte úroveň (tier) podľa toho, čo váš zásuvný modul obsahuje.

Úroveň Obsahuje Musí deklarovať
skills-only Zručnosti v manifeste a nič iné skills[], s aspoň jednou položkou
ui-only Frontendové rozhranie vo vnútri prostredia (shell) frontend
full-service Backend a frontend, zvyčajne s vlastnou schémou backend a frontend; a pretože má backend, aj runtime.healthCheck

Ak si nie ste istí, vygenerujte kostru full-service a odstráňte to, čo nepotrebujete. Opačný postup znamená dopisovať časti, ktoré by vám šablóna poskytla.

Prehliadka šablóny plnohodnotnej služby

Šablóna je referenčný zásuvný modul, zostavený podľa prísneho vzoru, ktorý predpokladá každá ďalšia kapitola. Klonujte jej tvar, nie jej ukážkovú logiku.

Cesta Čo to je
nexus.manifest.json Manifest v2: zopakované tri zákony, tabuľka smerovania (route table) a jej register práv
src/config.ts Zavádzač konfigurácie. Jedna špecifikácia, prečítaná raz, všetky problémy zozbierané predtým, než sa proces odmietne spustiť
src/scope.ts Jediný súbor, ktorý mení požiadavku na rozsah (scope), s prísnym overovačom tokenov zo súpravy SDK a dvoma režimami: doručiteľský token (bearer token) osoby a servisné volanie platformy
src/db.ts Každý príkaz skladá tenantFence() a beží vo vnútri withScopedTx
src/uno.ts Jediný súbor odosielania (dispatch): jedna adresa URL, jeden klient, uzavretý zoznam povolených položiek (allow-list)
src/routes/*.ts health (anonymná, presná cesta), trasy /api (s obmedzeným rozsahom) a spätné volanie /internal (chránené službou)
src/skills/sentiment.ts Deterministická zručnosť host_callback; nahraďte lexikón vlastnou logikou
src/server.ts Koreň kompozície: raz nainštaluje účtovnú knihu odmietnutí (refusal ledger), počká na databázu (časovo ohraničené) a pred spustením počúvania vykoná kontroly izolácie a účtovnej knihy
migrations/000_tenancy.sql Vygenerované nástrojom nexus-tenancy render v čase vytvárania kostry: roly, schéma, šablóna zabezpečenia na úrovni riadkov
migrations/001_init.sql Dve tabuľky so zloženým kľúčom začínajúcim nájomcom (tenant) a zloženým cudzím kľúčom nesúcim nájomcu
migrations/002_refusal_ledger.sql Tabuľka, do ktorej zapisuje účtovná kniha odmietnutí
scripts/ci/required-env Vypíše názvy premenných prostredia vyžadovaných pri štarte ako JSON
scripts/ci/shadow-migrate-*.sh Skúšobný beh (dry run) migrácie v pipeline, cez nexus-migrate
gates/ Adresár výnimiek pre kontrolné brány: prázdny, čo je správny stav pre nový zásuvný modul
test/ Testy pre rozsah, trasy, databázu, odosielanie a štart, s dvojníkmi rozsahu (scope doubles), ktorých vstrekuje každý test
Dockerfile Obraz bez oprávnení správcu (non-root, ID používateľa 10001) s migráciami vo vnútri

Niekoľko z týchto súborov si zaslúži bližší pohľad.

src/config.ts sa riadi dvoma pravidlami. Pred vyvolaním výnimky zozbiera každý problém, takže jeden reštart vymenuje všetkých päť chýbajúcich premenných namiesto piatich reštartov, z ktorých každý pomenuje jednu. A predvolenú hodnotu priradí len vtedy, keď nesprávna hodnota nemôže spôsobiť tichú nesprávnu odpoveď: PORT môže mať predvolenú hodnotu 8080, pretože nesprávny port viditeľne zlyhá pri naviazaní (bind), zatiaľ čo DATABASE_URL a UNO_DISPATCH_URL sú povinné a musia byť adresami v rámci klastra. Verejná adresa je pri štarte odmietnutá.

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

Vlastný test šablóny spustí tento súbor a porovná jeho výstup s názvami, ktoré špecifikácia konfigurácie označuje ako povinné, takže pridanie povinnej premennej bez aktualizácie zoznamu spôsobí zlyhanie npm test.

src/server.ts nezačne počúvať, kým sa neozve databáza, a čakanie ohraničí na 120 sekúnd, pričom zaznamená každý neúspešný pokus aj s jeho príčinou. Potom v uvedenom poradí preukáže, že aplikačná rola nedokáže premapovať nájomcu a každá tabuľka má vynútené zabezpečenie na úrovni riadkov, že oblasť pripojení (pool) každého podu sa zmestí do limitu pripojení danej roly a že tabuľka účtovnej knihy odmietnutí dokáže prijať riadok. Odmietnutie v ktoromkoľvek z týchto troch bodov sa vypíše v celom rozsahu a proces sa ukončí s kódom 2.

Manifest v2, pole po poli

Manifest je strojovo čitateľná zmluva zásuvného modulu s platformou. Validuje sa, keď ho vytvárate, keď ho platforma nasadzuje (onboarduje) a následne nepretržite. Schéma má nastavené additionalProperties: false na každej úrovni: ak má váš zásuvný modul sekciu, existuje pre ňu vlastnosť, a nedeklarovaný kľúč je odmietnutý. Riešením je vždy použiť správnu voliteľnú vlastnosť.

Povinné jadro

Pole Pravidlo
manifestVersion Presne "2". Dokument verzie v1 sa migruje, nikdy sa opätovne nevaliduje na pôvodnom mieste
name ^[a-z0-9]+([-.][a-z0-9]+)*$, najviac 64 znakov. ID zásuvného modulu používané pri registrácii, menných priestoroch odosielania (dispatch) a riadkoch viazaných na nájomcu. Zásuvný modul, ktorý deklaruje zručnosti, potrebuje aj názov bez bodky a bez úvodnej číslice
displayName 1 až 120 znakov
version Sémantická verzia; váš vlastný cyklus vydaní
description, author, license Každá položka aspoň jeden znak
tier skills-only, ui-only alebo full-service
trust core, verified, community alebo untrusted
runtime Povinné: executionMode, isolationLevel (1 až 4), entrypoint. Voliteľné: nodeVersion, healthCheck, readinessCheck, livenessCheck, každá položka je cesta začínajúca znakom /. Režim sa odvodzuje od úrovne: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker
architecture compute, ai a deploy, tri zopakované zákony platformy. Validátor vyžaduje presné znenie

Pre zásuvný modul, ktorý vytvárate pre svoju vlastnú inštaláciu, znejú tieto tri vety nasledovne. Veta ai pokrýva umelú inteligenciu (AI) a je miestom, kde sa uvádza, že zásuvný modul neuchováva žiadne prihlasovacie údaje modelov.

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

Tabuľka smerovania: api a rights

api vyžaduje version a basePath, a voliteľne websocket (path, auth) a endpoints[]. Tabuľka smerovania je najsilnejšou myšlienkou v schéme: kontrolná brána ju obojsmerne porovnáva s trasami, ktoré váš kód skutočne registruje, takže manifest je kontrolovateľnou zmluvou a nie iba dokumentáciou.

Každý koncový bod vyžaduje method (GET, POST, PUT, PATCH alebo DELETE) a path. Zvyšok:

Pole Čo uvádza
auth Jedna z piatich tried: scope (trasa osoby, za strážcom rozsahu), service-key a internal (server na server, nikdy nedosiahnuteľné z prehliadača), public (vždy iba presná cesta s allowAnonymous) a device (stroj s vlastným poverením, za strážcom zariadenia)
right Povinné na každej trase, ktorú obsluhuje strážca rozsahu, a odmietnuté na akejkoľvek inej: názov práva v registri rights
needsUnit Trasa odmietne požiadavku, keď nie je možné vyriešiť jednotku volajúceho
allowAnonymous Iba zoznam povolených položiek s presnou zhodou. Pravidlo prefixu je spôsob, akým sa /health-of-tenant-42 stane verejným
group, serves, screens Pod blokom release: skupina schopností (capability group), ktorú trasa obsluhuje, čo odpovie, keď je licencovaná funkcia danej skupiny uzamknutá (data, teaser, sighting alebo ask), a obrazovky, ktoré obsluhuje
query required (každý názov s ukážkovou hodnotou) a allowed: parametre dopytu, ktoré trasa číta
body example: ukážkové telo trasy pre zápis, také, ktoré jej vlastný validátor prijme. Nikdy nie pri metóde GET

rights je register, na ktorý sa tieto trasy odvolávajú. Každé právo má roles (strop) a voliteľne summary, never (roly, ktoré ho nikdy nesmú uplatniť, bez ohľadu na to, čo iné majú), barred (vlastné slová produktu pre odmietnutie roly never), seat (je potrebné aj aktívne miesto – live seat), self (má ho každá overená osoba pre práva nad svojou vlastnou reláciou), grants (držitelia udeľujú miesta; uvádza to najviac jedno právo), licence (licencovaná funkcia, ktorú musí obsahovať licencia organizácie) installation (majú ho iba vlastní administrátori inštalácie) a platform (majú ho iba administrátori platformy Adverant; neuvádza žiadne roly). Názvy práv obsahujú aspoň jednu bodku: 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 odmietne trasu rozsahu bez práva (ENDPOINT_RIGHT_MISSING), právo, ktoré v registri chýba (ENDPOINT_RIGHT_NOT_REGISTERED), a právo na trase, ktorú neobsluhuje žiadny strážca (ENDPOINT_RIGHT_UNGUARDED). Taktiež odmietne register, ktorý si protirečí, a dva rôzne zápisy jednej trasy (:id a :recordId) ako DUPLICATE_ENDPOINT.

Vaše údaje: databases, schema a db

schema je jediná schéma databázy Postgres, ktorú zásuvný modul vlastní. Hodnoty public, plugins, auth a nexus sú zakázané, a ak databases[] taktiež uvádza schému databázy Postgres, tieto dve sa musia zhodovať.

databases[] deklaruje každé úložisko podľa enginu: postgresql (schema, tables, migrations a granted, tabuľky, ktoré môže čítať iná organizácia na základe zaznamenaného oprávnenia), neo4j (schemas), qdrant (collections) alebo redis (purpose).

db uchováva limity relácií pre každé pripojenie, ktoré zásuvný modul otvorí; sú deklarované tu a nie v kóde, aby si ich mohol prečítať revízor aj proces nasadenia:

Pole Čo ohraničuje
maxConnections Oblasť pripojení (pool) na jednu repliku
pods Najväčší počet podov držiacich oblasť pripojení naraz, teda repliky plus nárazové navýšenie (surge) pri postupnej aktualizácii (rolling update). Limit pripojení každej roly sa vygeneruje ako maxConnections × pods; ak ho vynecháte, definePlugin vypíše varovanie DB_PODS_UNDECLARED
statementTimeoutMs Jeden príkaz
idleInTransactionTimeoutMs Otvorená transakcia, v ktorej nič nebeží
workMemKB Jeden uzol triedenia (sort) alebo hašovania (hash), na uzol, nie na dopyt
piiMask[] Položky table.column obsahujúce osobné údaje, maskované v riadenej konzole SQL a v záznamoch (logoch)

Zručnosti a nástroje: skills, mcpTools, entitlements

skills[] uchováva zručnosti manifestu; kapitola 2.20, Zručnosti, pokrýva ich polia a úrovne. mcpTools[] uchováva nástroje MCP (Model Context Protocol), ktoré zásuvný modul publikuje, pričom každý má name, description a inputSchema bez oneOf, allOf alebo anyOf na najvyššej úrovni.

entitlements vyžaduje featureIdPattern a prijíma alwaysOn[], source a store. Vzor určuje menný priestor, v ktorom sa nachádzajú vaše identifikátory funkcií, konvenčne name zásuvného modulu plus jeden segment, ktorý váš kód dopĺňa pre každé rozhranie (surface). alwaysOn[] je krátky, presný zoznam, ktorý musí odpovedať, aj keď nie je možné získať verdikt o oprávnení (entitlement): stav zdravia (health), pripravenosť (readiness), prihlásenie a nastavenia, ktoré administrátor potrebuje na opravu oprávnenia.

Riadenie zmien: changePolicy

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

Schválenia sa počítajú v rôznych osobách a osoba, ktorá zmenu navrhla, nikdy nie je jednou z nich; bez oboch týchto podmienok sa „dve schválenia“ zmenia na jednu osobu, ktorá klikne dvakrát. enabled: true vyžaduje classes a každá uvedená trieda potrebuje svoj vlastný počet. Trieda, ktorú vynecháte, nie je riadená, čo je legitímna voľba, ktorú vás schéma prinúti zapísať.

Kto ste: domains, branding, routing

domains[] (každá má primary a aliases[]; domain je forma pre jednu doménu) uvádza, kde zásuvný modul odpovedá. branding vyžaduje appName a prijíma tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId a gaId. Všetko v branding je verejné: prihlasovacia stránka to číta skôr, než má ktokoľvek prihlasovacie údaje, takže nikdy neobsahuje tajomstvo ani internú adresu. routing (type, gateway, virtualService) je pre zásuvné moduly, ktoré opisujú svoje vlastné smerovanie.

Dimenzovanie a zvyšok

resources vyžaduje cpuMillicores (10 až 64 000) a memoryMB (16 až 262 144) a prijíma diskGB, timeoutMs, port a wsPort. backend uchováva port, healthPath, apiPrefix, framework a platformClients[], klientov SDK, ktorých váš backend importuje podľa názvu. Zoznam je uzavretý a kontrolná brána ho porovnáva s vašimi importmi. Schéma povoľuje štrnásť názvov: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin a uno, plus jeden pre klienta, ktorý odpovedá na odmietnutia oprávnení plánu, ktorý si ponecháva interný názov. Klient oprávnení funkcií, runtime/entitlements, nie je jedným z nich a nikdy sa do zoznamu nezapisuje, pretože ho už deklaruje váš blok entitlements, a backend, ktorý ho importuje bez bloku entitlements, neprejde tou istou kontrolnou bránou. frontend uchováva basePath, mountPath a framework. nexus uchováva minVersion, maxVersion, capabilities[] a permissions[].

Zostávajúce bloky sú tam každý na jednu úlohu:

Blok Účel
settings Vaše nastavenia na zdieľanom frameworku: groups a keys, nastavené na úrovniach, ktoré každé z nich menuje
people sweep (service, port): členovia organizácie, synchronizovaní zo služby identity, s vypnutím miest (seats), keď niekto odíde
ontology entityTypes a relationshipTypes: typovaný graf udržiavaný vo vašej vlastnej schéme
release groups a frame: skupiny schopností, v ktorých sú vaše trasy fázované, vydávané najprv ako kanárikové nasadenie (canary)
cells[] Zásuvný modul, ktorý pozostáva z niekoľkých nasaditeľných celkov (deployables): každý má name, kind, entrypoint, port, wsPort
pricing model, currency, tiers[] pre váš záznam v katalógu
marketplace category, icon, screenshots, documentation, featured
compliance instruments[], dataResidency, sovereignty
developer, repository, keywords Kto ho publikuje a kde sa nachádza jeho kód
metrics, atlas Dva zámerne otvorené objekty pre vaše vlastné názvy metrík a generovanie dokumentácie architektúry

Čo schéma nedokáže vyjadriť

Schéma JSON určuje tvar; definePlugin pridáva pravidlá, ktoré schéma nedokáže vyjadriť. Hodnota classification zručnosti nemôže prekročiť strop dôveryhodnosti. Iba zásuvné moduly core a verified môžu deklarovať zručnosti tool_using a llm_only. Každá deklarovaná cesta musí byť relatívna a rovnakého pôvodu (same-origin), bez schémy, bez // a bez spätného lomítka, pretože analyzátor URL prevádza \ na / a /\evil.example/x sa vyhodnotí ako cudzí pôvod (cross-origin). Každé pravidlo, ktoré synchronizácia registra uplatňuje na zručnosť, sa uplatní najprv tu, s vlastným kódom synchronizácie, takže validate a synchronizácia pomenujú porušené pravidlo rovnakým spôsobom.

Validácia a prechod z verzie 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

Zlyhanie vypíše presnú cestu a v prípade pravidla synchronizácie najprv kód. Urobte z toho háčik odoslania (commit hook).

Manifest v1 sa povýši mechanicky. migrate pridá tri vety zákonov, presunie domain do domains[] a odmietne si vymyslieť vstupný bod, ktorý ste nemali. Pred vypísaním alebo zapísaním čohokoľvek zvaliduje výsledok, takže migrácia nikdy nepresunie chybu z nástroja do vášho repozitára.

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

Pred odoslaním do repozitára (commit) si prečítajte rozdiely (diff). Vety zákonov, ktoré pridáva, sú znením, ktoré vyžaduje validátor; pre svoju vlastnú inštaláciu nastavte deploy na vetu uvedenú vyššie.

Vykreslenie tenanta a zriadenie rolí

Oprávnenia rolí ani šablónu zabezpečenia na úrovni riadkov nikdy nepíšete ručne. nexus-tenancy render ich zapíše z položiek schema a db v manifeste:

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

Vygenerovaný súbor vytvorí pre schému päť rolí, každú s tým, čo nesmie mať: migrátora, ktorý sa môže stať iba vlastníkom, vlastníka, ktorý sa nemôže prihlásiť, aplikačnú rolu pre cestu požiadavky, reportovaciu rolu, ktorá vidí iba agregáty, a rolu účtovnej knihy (ledger), ktorá môže iba pridávať záznamy. Žiadna rola nemá BYPASSRLS. Jediný spôsob, ako naviazať nájomcu, je jedna databázová funkcia a set_config je odobraté každej role okrem vlastníka.

Aplikovaný súbor viacnásobného prenájmu (tenancy) sa nikdy neupravuje. Zmena je revíziou s vlastným súborom s číslom 0 a miesto na čítanie (read seat) pre oprávnenia medzi organizáciami prichádza týmto spôsobom ako revízia 2. --graph vygeneruje dve tabuľky typovaného grafu, ktoré deklaruje váš ontology, ako vašu ďalšiu očíslovanú migráciu.

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

Súbor viacnásobného prenájmu vytvára práve tie roly, pod ktorými sa spúšťač pripája, takže ho aplikuje vlastník databázy pomocou 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> je pripojovací reťazec pre vlastníka databázy a <dir> je súkromný adresár. Zriadenie (provision) aplikuje základný súbor viacnásobného prenájmu a každú revíziu v príslušnom poradí, zapíše migrator.url a app.url (a seat.url, keď už existuje revízia 2) do <dir> s režimom 0600 a nevypíše nič tajné. Pri každom behu nastaví limit pripojení každej roly z db.maxConnections × db.pods. Opätovné spustenie zachová existujúce heslá, pokiaľ nepožiadate o zmenu: --passwords <dir> ich nastaví zo súborov a --rotate <roles> pridelí uvedeným rolám nové heslá. Premeňte tieto súbory na tajomstvá (secrets) vášho nasadenia.

Potom sa aplikovanie migrácií pripojí pomocou pripojovacieho reťazca migrátora, ktorý zapísalo zriadenie:

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

Spúšťa súbory od 001 ďalej ako migrátor, každý súbor pod SET ROLE <schema>_owner, jedna transakcia na súbor. Udržiava účtovnú knihu, <schema>.schema_migrations, s kontrolným súčtom každého súboru; aplikovaný súbor, ktorého bajty sa zmenili, je odmietnutý podľa názvu (CHECKSUM_DRIFT), nikdy sa nespustí znova a nikdy sa nepreskočí. Každý čakajúci súbor je pred spustením prvého z nich analyzovaný skutočnou gramatikou databázy Postgres, takže odmietnutie ponechá databázu nedotknutú. Jediná hlavička, ktorú môže súbor niesť, je -- nexus-migration: transaction=file|per-statement, s voliteľnými časovými limitmi zámku a príkazu; per-statement je pre CREATE INDEX CONCURRENTLY.

Brány

nexus-gates spúšťa dvadsaťdva kontrolných brán. Každá kóduje jednu triedu chýb, aby sa nemohla nasadiť dvakrát, a každá má autotest, ktorý dokazuje, že zlyhá na testovacej vzorke (fixture) zostavenej tak, aby ju spustila. Spustite ich pred odoslaním zmien (push):

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test
Kontrolná brána Čo zachytáva
scope-adherence Trasu /api bez strážcu rozsahu; anonymnú cestu, ktorá nie je presne deklarovanou cestou; trasu zariadenia bez strážcu zariadenia alebo so strážcom osoby vedľa neho
one-fence Predikát nájomcu definovaný kdekoľvek inde ako na jednom mieste, vrátane ručne napísaného ohraničenia (fence) miesta alebo oprávnenia
sql-fence Príkaz čítajúci alebo aktualizujúci tabuľku s obmedzeným rozsahom bez ohraničenia, v akomkoľvek cieli FROM, JOIN, USING alebo UPDATE
migrations-are-scoped Tabuľku, ktorej chýba os, zložený kľúč začínajúci nájomcom, cudzí kľúč nesúci nájomcu alebo stĺpec demo
migrations-commit-what-they-open Migráciu, ktorej počet BEGIN sa nezhoduje s jej počtom COMMIT a ROLLBACK
no-direct-compute Priame volanie poskytovateľa modelu, enginu, frontu alebo hostiteľa pracovných postupov (workflow); druhého čitateľa adresy URL odosielania (dispatch)
no-credentials Prihlasovacie údaje poskytovateľa modelu čitateľné v repozitári alebo v prostredí
crud-adherence Modifikujúcu trasu, ktorej kontrola práv neuvádza nič z registra
blocked-backends Trasu, ktorá nie je ani obsluhovaná, ani blokovaná podľa názvu, ani odmietnutá zo zákona, ani vlastnená niekde inde
every-test-runs Testy, na ktoré vzor (glob) testovacieho skriptu nikdy nedosiahne
tiles-are-invariant Spoj (seam) vo vyrovnávacej pamäti nemenný voči nájomcovi, ktorý číta hodnotu nájomcu alebo preskakuje autentifikáciu
api-contract Zaregistrovanú trasu, ktorú manifest nedeklaruje, alebo deklarovanú trasu, ktorú kód nikdy nezaregistruje
rls-present Tabuľku bez vynúteného zabezpečenia na úrovni riadkov; funkciu SECURITY DEFINER bez zafixovanej search_path
no-set-config Kód zásuvného modulu, ktorý si sám nastavuje väzbu nájomcu
db-role-honest Cestu požiadavky pripájajúcu sa ako vlastník alebo migrátor, alebo žiadajúcu o SUPERUSER či BYPASSRLS
platform-clients Klienta SDK, ktorý je importovaný, ale nie je uvedený v backend.platformClients, alebo je uvedený, ale nikdy nie je importovaný
rights-register Trasu rozsahu bez deklarovaného práva; kontrolu práva mimo registra
refusal-ledger Deklarovanú tabuľku odmietnutí bez nainštalovanej účtovnej knihy, alebo telo odmietnutia odoslané mimo nej
grants-declared Tabuľku s udeleným oprávnením, ktorú manifest nedeklaruje; privilégiá miesta na čítanie (read-seat) rozdané ručne
people-declared Blok people bez jeho čistiacej trasy (sweep route), strážcu a tabuliek
functions-closure Zásuvný modul Azure Functions, ktorého obsluhované trasy a deklarované trasy sa nezhodujú
declared-input Zoznam parametrov dopytu obslužnej rutiny (handler), ktorý sa nezhoduje s deklarovaným query trasy

Adresár gates/ uchováva päť súborov výnimiek, ktoré môže kontrolná brána čítať (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json a invariant-seams.json), jeden dôvod na položku. Prázdny dôvod sa počíta ako žiadna položka a položka pomenúvajúca niečo, čo už neexistuje, spôsobí zlyhanie kontrolnej brány. Môžete tam tiež vložiť svoje vlastné moduly kontrolných brán a nexus-gates ich načíta popri tých vstavaných.

Kompatibilita
Kompatibilita
Kompatibilita ukazuje, ktorá verzia SDK funguje s ktorou verziou platformy, na základe nočných behov rýchleho štartu (quickstart). Netestovaná dvojica to o sebe uvádza a zlyhávajúca dvojica menuje zmenu, ktorá ju pokazila.

Potrubie (pipeline) šablóny

Šablóna nedodáva žiadny ručne písaný pracovný postup (workflow). Jej konfigurácia pipeline menuje Dockerfile, jediný argument zostavenia (token registra), skúšobný beh migrácie a sondu štartu, a kontrolnú bránu, ktorú spúšťa front zlučovania (merge queue). Poradie zodpovedá poradiu, v akom by ste chceli zachytiť prípadné zlyhanie.

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

Okolo obrazu bežia ešte dve kontroly. Skúšobný beh migrácie aplikuje každý súbor na jednorazový Postgres predtým, než môže byť obraz vydaný, s tým istým spúšťačom, aký používa produkcia: nexus-migrate provision raz ako superpoužívateľ, potom každý očíslovaný súbor ako migrátor. Štartovacia sonda spustí zostavený obraz s jeho vlastným vstupným bodom a každou premennou, ktorú required-env vypíše, nasmerovaný na náhrady, ktoré prijímajú spojenia a nikdy neodpovedajú. Server čaká na databázu v rámci svojho ohraničeného okna a toto čakanie je signálom úspešného prechodu; zavádzač konfigurácie, ktorý odmietne naštartovať, zhodí zostavenie tam a nie v produkcii.

Vývoj v edícii Community
Vývoj v edícii Community
V edícii Community dostane vývojár tie isté osvedčené postupy, vývojový priestor a dátové vetvy na jednom serveri, s kódom na vlastnom Git hostingu. Staging, pilotné jednotky a maskované kópie živých dát prichádzajú s edíciou Enterprise.

Koľko to stojí

SDK vám berie rozhodnutia z rúk a niektoré z nich by ste urobili inak. Manifest odmieta kľúče, ktoré nepozná, tabuľka smerovania sa musí presne zhodovať s vaším kódom, databázové roly nenavrhujete vy a kontrolné brány zhodia zostavenie pre chýbajúce oprávnenie pri čítaní. Pri mojom prvom zásuvnom module som strávil deň dohadovaním sa s api-contract o trase, ktorú som zaregistroval a zabudol deklarovať. Mal pravdu; trasa bola nechránená. Očakávajte, že prvý zásuvný modul sa bude zdať pomalý, a očakávajte, že ten druhý zaberie tretinu času.