Versioon 1.0.0-alpha.1uusim
Peatükk 2.21
Plugin SDK
Plugin SDK (tarkvaraarenduskomplekti) paigaldamine, selle käsureatööriistad, täisteenuse malli tutvustus, v2 manifest välihaaval ja kakskümmend kaks väravat, mis hoiavad pistikprogrammi reeglite piires.
Selle lehe tõlkis AI ingliskeelsest originaalist. Kui miski jääb ebaselgeks, võtke aluseks ingliskeelne leht. Lugege seda lehte inglise keeles

Minu teise plugina loomine võttis kolmandiku esimesele kulunud ajast ning peaaegu kogu ajavõit tuli SDK-st (tarkvaraarenduskomplektist). Esimesel korral kirjutasin skoopide kontrolli, konfiguratsioonilaaduri ja migratsioonide käivitaja ning ülevaataja saatis need kõik tagasi. Teisel korral käivitasin ühe alusstruktuuri loomise käsu, kustutasin näiteks olnud meelsusoskuse ja pühendasin oma päevad anomaaliate ülevaatuse kirjetele, mida meie lennudünaamika meeskond tegelikult vajas.
@adverant-nexus/plugin-sdk on üks npm-i pakett. See sisaldab v2-manifesti skeemi ja seda lugevaid validaatoreid (definePlugin, defineSkill), käitusaja mooduleid, mida teie plugin impordib skoobi, andmebaasi, edastuse ja muu jaoks, testide abifunktsioone, vastavuskontrolle (adherence gates) ning käsureatööriistu. See peatükk käsitleb selle paigaldamist, tööriistu, malli, manifesti ja vastavuskontrolle. Peatükk 2.22, Plugina käituskeskkond, käsitleb käitusaja mooduleid teie töötavas koodis.
Paigaldamine
Pakett pärineb Adveranti registrist aadressil https://registry.adverant.ai/npm/, mitte kunagi avalikust npm-i registrist, ning te vajate tõmbeluba (pull token) oma konto lehelt „Pull tokens and install commands”. Suunake @adverant-nexus skoop oma hoidla failis .npmrc sellele registrile:
@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>
<pull-token> on luba teie konto lehelt. Konveieris (pipeline) edastage see saladusest (secret) ja ärge kunagi lisage seda versioonihaldusesse (commit); malli Dockerfile keeldub ilma selleta ehitamast ja kustutab .npmrc ehitusetapist kohe, kui npm ci on käivitatud, nii et luba ei jõua kunagi tõmmisesse.
Seejärel fikseerige täpne versioon:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Lisage package-lock.json versioonihaldusesse esimesel paigaldamisel. Malli tõmmise ehitamine käivitab käsu npm ci ja keeldub tagasi langemast käsule npm install: lukustusfail on leping. SDK enda alampiir on Node 18; mall on suunatud versioonile Node 20.
Käsureatööriistad tarnitakse paketi sees, seega nimetab iga selles dokumentatsioonis olev käsk paketi ja selle versiooni kujul npx -p. Eraldiseisvalt otsitakse npx create-nexus-plugin avalikust registrist ja see nimi ei ole see pakett.
Käsureatööriistad
| Tööriist | Mida see teeb |
|---|---|
create-nexus-plugin |
Loob plugina alusstruktuuri, valideerib manifesti, migreerib v1-manifesti versioonile v2 ja genereerib teie kasutajaliidese arendajale tarbijajuhendi |
nexus-tenancy |
Genereerib manifestist teie skeemi rentnike (tenancy) SQL-i: rollid, õigused, reataseme turvalisuse malli ja graafitabelid |
nexus-migrate |
Rakendab teie migratsioonid: valmistab rollid ühe korra ette, seejärel käivitab iga nummerdatud faili migreerija rollis |
nexus-gates |
Käivitab kõik vastavuskontrollid ja iga kontrolli enda enesetesti |
create-nexus-plugin ei tee võrgupäringuid ega laadi kaugkoodi. See käivitab samu protsessisiseseid validaatoreid, mida käivitab platvormi kasutuselevõtu protsess (onboarding), seega ei teki lahknevust olukordade „see valideerus minu masinas” ja „platvorm võttis selle vastu” vahel.
| Käsk | Lipud | Mida see teeb | Väljumiskoodid |
|---|---|---|---|
scaffold <name> |
--tier full-service\|ui-only\|skills-only, --dir <path>, --print |
Kirjutab uue plugina kataloogi; --print prindib ainult manifesti |
0 kirjutatud · 1 keeldus üle kirjutamast · 2 vale kasutus |
validate <file> |
Valideerib üksuse nexus.manifest.json või mooduli .ts või .js, mis seda ekspordib |
0 kehtiv · 1 kehtetu või loetamatu · 2 vale kasutus | |
migrate <file> |
--write |
Tõstab v1-manifesti versioonile v2 ja prindib selle või kirjutab selle samasse kohta üle | 0 · 1 · 2, nagu ülal |
guide |
--manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint |
Genereerib manifestist ja teie kirjeldusest tarbijajuhendi; --check võrdleb seda versioonihalduses oleva koopiaga ega kirjuta midagi |
0 · 1 lahknevus või lintimise rikkumine · 2 vale kasutus |
help |
Prindib kasutusjuhendi | 0 |
Alusstruktuuri loomine ja kolm taset
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-service--tier vaikimisi väärtus on full-service. Alusstruktuuri looja keeldub kirjutamast juba olemasolevasse kataloogi ja tema kirjutatud manifest läbib juba valideerimise; see ei väljasta kunagi kehtetut manifesti.
Valige tase selle järgi, mis teie pluginal on.
| Tase | Sisaldab | Peab deklareerima |
|---|---|---|
skills-only |
Ainult manifesti oskused ja mitte midagi muud | skills[], vähemalt ühe kirjega |
ui-only |
Kasutajaliidese pind kesta (shell) sees | frontend |
full-service |
Taustasüsteem ja kasutajaliides, tavaliselt oma skeemiga | backend ja frontend; ning kuna sellel on taustasüsteem, siis runtime.healthCheck |
Kui te pole kindel, looge alusstruktuur tasemega full-service ja kustutage see, mida te ei vaja. Vastupidine tee tähendab nende osade kirjutamist, mille mall oleks teile juba andnud.
Täisteenuse malli tutvustus
Mall on etalonplugin, mis on ehitatud range mustri järgi, mida iga järgnev peatükk eeldab. Kloonige selle kuju, mitte selle näidisloogikat.
| Asukoht | Mis see on |
|---|---|
nexus.manifest.json |
v2-manifest: kolm seadust uuesti sõnastatuna, marsruuditabel ja selle õiguste register |
src/config.ts |
Konfiguratsioonilaadur. Üks spetsifikatsioon, loetakse korra, kõik probleemid kogutakse kokku, enne kui protsess keeldub käivitumast |
src/scope.ts |
See üks fail, mis muudab päringu skoobiks, kasutades SDK ranget loakontrollijat ja kahte režiimi: isiku esitajaluba (bearer token) ja platvormi teenusekutse |
src/db.ts |
Iga lause koostab üksuse tenantFence() ja käivitub üksuse withScopedTx sees |
src/uno.ts |
See üks edastusfail (dispatch file): üks URL, üks klient, suletud lubatud nimekiri |
src/routes/*.ts |
health (anonüümne, täpne asukoht), /api marsruudid (skoobitud) ja /internal tagasikutse (teenuse-kaitstud) |
src/skills/sentiment.ts |
Deterministlik host_callback oskus; asendage leksikon oma loogikaga |
src/server.ts |
Kompositsioonijuur: paigaldab keeldumiste pearaamatu (refusal ledger) ühe korra, ootab andmebaasi (piiratud ajaga), seejärel käivitab enne kuulamise alustamist isolatsiooni- ja pearaamatu kontrollid |
migrations/000_tenancy.sql |
Genereeritud tööriista nexus-tenancy render poolt alusstruktuuri loomise ajal: rollid, skeem, reataseme turvalisuse mall |
migrations/001_init.sql |
Kaks tabelit rentnikuga algava liitvõtmega ja liit-, rentnikku kandva võõrvõtmega |
migrations/002_refusal_ledger.sql |
Tabel, kuhu keeldumiste pearaamat kirjutab |
scripts/ci/required-env |
Prindib käivitamiseks nõutavate keskkonnamuutujate nimed JSON-vormingus |
scripts/ci/shadow-migrate-*.sh |
Konveieri migratsiooni proovikäivitus (dry run), läbi tööriista nexus-migrate |
gates/ |
Vastavuskontrollide erandite kataloog: tühi, mis on uue plugina jaoks õige olek |
test/ |
Testid skoobi, marsruutide, andmebaasi, edastuse ja käivitamise jaoks, koos skoobi dublantidega (doubles), mida iga test süstib |
Dockerfile |
Mitte-juurkasutaja tõmmis (kasutaja ID 10001) koos selle sees olevate migratsioonidega |
Mõned neist failidest väärivad lähemat uurimist.
src/config.ts järgib kahte reeglit. See kogub enne vea viskamist kokku kõik probleemid, nii et üks taaskäivitus nimetab kõik viis puuduvat muutujat, selmet teha viis taaskäivitust, mis nimetavad igaüks ühe. Ja see määrab vaikeväärtuse ainult siis, kui vale väärtus ei saa anda vaikset valet vastust: PORT võib vaikimisi olla 8080, sest vale port nurjab sidumise nähtavalt, samas kui DATABASE_URL ja UNO_DISPATCH_URL on nõutavad ja peavad olema klastrisisesed aadressid. Avalik aadress lükatakse käivitamisel tagasi.
node scripts/ci/required-env["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]
Malli enda test käivitab selle faili ja võrdleb selle väljundit nimedega, mille konfiguratsiooni spetsifikatsioon märgib nõutavaks, nii et nõutava muutuja lisamine ilma nimekirja uuendamata nurjab käsu npm test.
src/server.ts ei alusta kuulamist enne, kui andmebaas vastab, ja piirab ooteaja 120 sekundiga, logides iga ebaõnnestunud katse koos põhjusega. Seejärel tõestab see järjekorras, et rakenduse roll ei saa rentnikku uuesti siduda ja iga tabel on sunnitud reataseme turvalisuse alla, et iga pod'i ühenduste kogum (pool) mahub rolli ühenduste limiiti ja et keeldumiste pearaamatu tabel suudab rida vastu võtta. Mis tahes kolmest tulenev keeldumine prinditakse tervikuna välja ja protsess väljub koodiga 2.
v2 manifest, välihaaval
Manifest on plugina masinloetav leping platvormiga. Seda valideeritakse siis, kui te selle kirjutate, kui platvorm selle kasutusele võtab ja pidevalt pärast seda. Skeem on igal tasemel additionalProperties: false: kui teie pluginal on sektsioon, on selle jaoks omadus, ja deklareerimata võti lükatakse tagasi. Lahendus on alati õige valikulise omaduse kasutamine.
Nõutav tuum
| Väli | Reegel |
|---|---|
manifestVersion |
Täpselt "2". v1-dokument migreeritakse, seda ei valideerita kunagi uuesti samas kohas |
name |
^[a-z0-9]+([-.][a-z0-9]+)*$, kuni 64 tähemärki. Plugina ID, mida kasutatakse registreerimisel, edastuse nimeruumides ja rentniku-skoobiga ridades. Plugin, mis deklareerib oskusi, vajab ka nime, milles pole punkti ja mis ei alga numbriga |
displayName |
1 kuni 120 tähemärki |
version |
Semantiline versioon; teie enda väljalaskeahel |
description, author, license |
Igaüks vähemalt üks tähemärk |
tier |
skills-only, ui-only või full-service |
trust |
core, verified, community või untrusted |
runtime |
Nõutav: executionMode, isolationLevel (1 kuni 4), entrypoint. Valikuline: nodeVersion, healthCheck, readinessCheck, livenessCheck, igaüks asukoht, mis algab märgiga /. Režiim tuletatakse tasemest: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker |
architecture |
compute, ai ja deploy, kolm platvormi seadust uuesti sõnastatuna. Validaator fikseerib sõnastuse |
Plugina puhul, mille ehitate omaenda paigalduse jaoks, kõlavad need kolm lauset järgmiselt. Lause ai hõlmab tehisintellekti (AI) ja on koht, kus öelda, et plugin ei oma mudeli mandaate.
"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."
}Marsruuditabel: api ja rights
api vajab omadusi version ja basePath ning valikuliselt websocket (path, auth) ja endpoints[]. Marsruuditabel on skeemi tugevaim idee: vastavuskontroll võrdleb seda mõlemas suunas marsruutidega, mida teie kood tegelikult registreerib, nii et manifest on kontrollitav leping, mitte dokumentatsioon.
Iga lõpp-punkt vajab omadusi method (GET, POST, PUT, PATCH või DELETE) ja path. Ülejäänud:
| Väli | Mida see ütleb |
|---|---|
auth |
Üks viiest klassist: scope (isiku marsruut, skoobikaitse taga), service-key ja internal (serverilt serverile, pole brauserist kunagi kättesaadav), public (alati ainult täpne asukoht koos omadusega allowAnonymous) ja device (oma mandaadiga masin, seadmekaitse taga) |
right |
Nõutav igal marsruudil, mida skoobikaitse teenindab, ja tagasi lükatud kõigil teistel: õiguse nimi registris rights |
needsUnit |
Marsruut keeldub, kui kutsuja üksust ei saa lahendada |
allowAnonymous |
Ainult täpse vastega lubatud nimekiri. Prefiksireegel on viis, kuidas /health-of-tenant-42 muutub avalikuks |
group, serves, screens |
Ploki release all: võimekuse grupp, mida marsruut teenindab, mida see vastab, kui selle grupi litsentsitud funktsioon on lukustatud (data, teaser, sighting või ask), ja ekraanid, mida see teenindab |
query |
required (iga nimi koos näidisväärtusega) ja allowed: päringuparameetrid, mida marsruut loeb |
body |
example: kirjutamismarsruudi näidiskeha, selline, mida tema enda validaator aktsepteerib. Mitte kunagi GET-päringul |
rights on register, mida need marsruudid nimetavad. Igal õigusel on roles (ülempiir) ja valikuliselt summary, never (rollid, mis ei tohi seda kunagi kasutada, sõltumata sellest, mis neil veel on), barred (toote enda sõnad rolli never tagasilükkamiseks), seat (vajalik on ka aktiivne töökoht (seat)), self (igal kinnitatud isikul on see, õiguste jaoks omaenda sessiooni üle), grants (omanikud annavad töökohti;limiidiks on, et vaid üks õigus ütleb nii), licence (litsentsitud funktsioon, mida organisatsiooni litsents peab kandma) installation (kuulub ainult paigalduse enda administraatoritele) ja platform (kuulub ainult Adveranti platvormi administraatoritele; see ei nimeta rolle). Õiguste nimedes on vähemalt üks punkt: 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 lükkab tagasi skoobimarsruudi, millel puudub õigus (ENDPOINT_RIGHT_MISSING), õiguse, mis registris puudub (ENDPOINT_RIGHT_NOT_REGISTERED), ja õiguse marsruudil, mida ükski kaitse ei teeninda (ENDPOINT_RIGHT_UNGUARDED). Samuti lükkab see tagasi registri, mis on endaga vastuolus, ja ühe marsruudi kaks kirjapilti (:id ja :recordId) veana DUPLICATE_ENDPOINT.
Teie andmed: databases, schema ja db
schema on see üks Postgresi skeem, mida plugin omab. public, plugins, auth ja nexus on keelatud, ja kui databases[] nimetab samuti Postgresi skeemi, peavad need kaks ühtima.
databases[] deklareerib iga andmehoidla mootori järgi: postgresql (schema, tables, migrations ja granted, tabelid, mida teine organisatsioon võib salvestatud loa alusel lugeda), neo4j (schemas), qdrant (collections) või redis (purpose).
db hoiab sessioonilimiite iga ühenduse jaoks, mille plugin avab; need on deklareeritud siin, mitte koodis, et nii ülevaataja kui ka juurutus saaksid neid lugeda:
| Väli | Mida see piirab |
|---|---|
maxConnections |
Ühenduste kogum (pool) replika kohta |
pods |
Maksimaalne pod'ide arv, mis hoiavad korraga ühenduste kogumit, replikad pluss rulluva uuenduse (rolling update) ajutine lisa. Iga rolli ühenduste limiit genereeritakse kujul maxConnections × pods; jätke see välja ja definePlugin hoiatab DB_PODS_UNDECLARED |
statementTimeoutMs |
Üks lause (statement) |
idleInTransactionTimeoutMs |
Avatud transaktsioon, mis ei käivita midagi |
workMemKB |
Üks sortimis- või räsissõlm (hash node), sõlme kohta, mitte päringu kohta |
piiMask[] |
table.column kirjed, mis sisaldavad isikuandmeid, maskeeritud hallatud SQL-konsoolis ja logides |
Oskused ja tööriistad: skills, mcpTools, entitlements
skills[] hoiab manifesti oskusi; peatükk 2.20, Oskused, käsitleb nende välju ja tasemeid. mcpTools[] hoiab MCP (Model Context Protocol) tööriistu, mida plugin avaldab, igaüks neist name, description ja inputSchema ilma tipptaseme omadusteta oneOf, allOf või anyOf.
entitlements nõuab omadust featureIdPattern ja aktsepteerib omadusi alwaysOn[], source ja store. Muster nimetab nimeruumi, milles teie funktsiooni ID-d elavad, tavapäraselt plugina name pluss üks segment, mille teie kood täidab pinna kohta. alwaysOn[] on lühike, täpne nimekiri, mis peab vastama isegi siis, kui õiguste otsust (entitlement verdict) ei ole võimalik saada: tervis, valmisolek, sisselogimine ja seaded, mida administraator vajab õiguse parandamiseks.
Muudatuste haldus: changePolicy
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Kinnitusi loetakse erinevates inimestes ja muudatuse esitanud isik ei ole kunagi üks neist; ilma mõlema pooleta muutub „kaks kinnitust” üheks inimeseks, kes klõpsab kaks korda. enabled: true nõuab omadust classes ja iga nimetatud klass vajab oma loendurit. Klass, mille välja jätate, on reguleerimata, mis on legitiimne valik, mille skeem sunnib teid kirja panema.
Kes te olete: domains, branding, routing
domains[] (igaüks primary ja aliases[]; domain on ühe domeeni vorm) loetleb, kus plugin vastab. branding nõuab omadust appName ja aktsepteerib omadusi tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId ja gaId. Kõik üksuses branding on avalik: sisselogimisleht loeb seda enne, kui kellelgi on mandaat, seega ei sisalda see kunagi saladust ega sisemist aadressi. routing (type, gateway, virtualService) on mõeldud pluginatele, mis kirjeldavad omaenda marsruutimist.
Suuruse määramine ja ülejäänu
resources nõuab omadusi cpuMillicores (10 kuni 64,000) ja memoryMB (16 kuni 262,144) ning aktsepteerib omadusi diskGB, timeoutMs, port ja wsPort. backend hoiab omadusi port, healthPath, apiPrefix, framework ja platformClients[], mis on SDK kliendid, mida teie taustasüsteem nime järgi impordib. Nimekiri on suletud ja vastavuskontroll võrdleb seda teie importidega. Skeem lubab neljateistkümmet nime: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin ja uno, pluss üks kliendi jaoks, mis vastab plaaniõiguste keeldumistele, mis säilitab sisemise nime. Funktsiooniõiguste klient, runtime/entitlements, ei ole üks neist ja ei lähe kunagi nimekirja, sest teie entitlements plokk juba deklareerib selle, ja taustasüsteem, mis impordib selle ilma entitlements plokita, põrub samas vastavuskontrollis. frontend hoiab omadusi basePath, mountPath ja framework. nexus hoiab omadusi minVersion, maxVersion, capabilities[] ja permissions[].
Ülejäänud plokid on igaüks mõeldud ühe töö jaoks:
| Plokk | Milleks |
|---|---|
settings |
Teie seaded jagatud raamistikus: groups ja keys, määratud tasemetel, mida igaüks nimetab |
people |
sweep (service, port): organisatsiooni liikmed, sünkroonitud identiteediteenusest, kusjuures töökohad lülitatakse välja, kui keegi lahkub |
ontology |
entityTypes ja relationshipTypes: tüübistatud graaf, mida hoitakse teie enda skeemis |
release |
groups ja frame: võimekuse grupid, millesse teie marsruudid on etapiviisiliselt jaotatud, avaldatud esmalt kanaarilinnuna (canary) |
cells[] |
Plugin, mis koosneb mitmest juurutatavast osast: igaühel name, kind, entrypoint, port, wsPort |
pricing |
model, currency, tiers[] teie kataloogikirje jaoks |
marketplace |
category, icon, screenshots, documentation, featured |
compliance |
instruments[], dataResidency, sovereignty |
developer, repository, keywords |
Kes selle avaldab ja kus selle kood elab |
metrics, atlas |
Kaks teadlikult avatud objekti teie enda mõõdikute nimede ja arhitektuuridokumentatsiooni genereerimise jaoks |
Mida skeem ei saa öelda
JSON-skeem määrab kuju; definePlugin lisab reeglid, mida skeem ei suuda väljendada. Oskuse classification ei tohi ületada usaldusväärsuse ülempiiri. Ainult core ja verified pluginad võivad deklareerida tool_using ja llm_only oskusi. Iga deklareeritud asukoht peab olema suhteline ja sama päritoluga (same-origin), ilma skeemita, ilma märgita // ja ilma kurakaldkriipsuta, sest URL-i parser voldib \ kujule / ja /\evil.example/x lahendub ristpäritoluna (cross-origin). Iga reegel, mida registri sünkroonimine oskusele rakendab, rakendatakse esmalt siin, sünkroonimise enda koodiga, nii et validate ja sünkroonimine nimetavad rikutud reeglit ühtemoodi.
Valideerimine ja üleminek versioonilt 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
Tõrge prindib täpse asukoha ja sünkroonimisreegli puhul esmalt koodi. Tehke sellest commit-konks (commit hook).
v1-manifest tõstetakse mehaaniliselt. migrate lisab kolm seaduselauset, liigutab domain asukohta domains[] ja keeldub leiutamast sisenemispunkti, mida teil polnud. See valideerib tulemuse enne millegi printimist või kirjutamist, nii et migratsioon ei vii tõrget kunagi tööriistast teie hoidlasse.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --writeLugege erinevusi (diff) enne, kui need versioonihaldusesse lisate. Seaduselaused, mille see lisab, on sõnastus, mille validaator fikseerib; omaenda paigalduse jaoks määrake deploy varem näidatud lausele.
Üürnikukeskkonna renderdamine ja rollide ettevalmistamine
Te ei kirjuta kunagi oma rolliõigusi ega reataseme turvalisuse malli käsitsi. nexus-tenancy render kirjutab need manifesti omadustest schema ja db:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sqlGenereeritud fail loob skeemi jaoks viis rolli, millest igaühel on määratud see, mida ta ei tohi omada: migreerija, mis saab muutuda ainult omanikuks, omanik, mis ei saa sisse logida, rakenduse roll päringu teekonna jaoks, aruanderoll, mis näeb ainult koondandmeid, ja pearaamatu roll, mis saab ainult ridu lisada. Ükski roll ei oma õigust BYPASSRLS. Ainus viis rentniku sidumiseks on üks andmebaasifunktsioon ja set_config on tühistatud kõigilt rollidelt peale omaniku.
Rakendatud rentnike faili ei muudeta kunagi. Muudatus on redaktsioon omaenda number-0 failiga ja lugemistöökoht (read seat) organisatsioonidevaheliste lubade jaoks saabub sel viisil, 2. redaktsioonina. --graph genereerib teie ontology deklareeritud tüübistatud graafi kaks tabelit teie järgmise nummerdatud migratsioonina.
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.sqlRentnike fail loob needsamad rollid, kellena käivitaja ühendub, seega rakendab seda andmebaasi omanik käsuga 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> on ühendusstring andmebaasi omaniku jaoks ja <dir> on privaatne kataloog. Ettevalmistus (provision) rakendab baasrentnike faili ja iga redaktsiooni järjekorras, kirjutab migrator.url ja app.url (ning seat.url, kui 2. redaktsioon on olemas) kataloogi <dir> režiimiga 0600 ega prindi midagi salajast. See määrab igal käivitamisel iga rolli ühenduste limiidi üksusest db.maxConnections × db.pods. Uuesti käivitamine säilitab olemasolevad paroolid, kui te just ei palu teisiti: --passwords <dir> määrab need failidest ja --rotate <roles> annab nimetatud rollidele värsked paroolid. Muutke need failid oma juurutuse saladusteks.
Pärast seda ühendub rakendamine migreerija ühendusstringiga, mille ettevalmistus kirjutas:
DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.jsonSee käivitab failid alates 001-st migreerijana, iga faili SET ROLE <schema>_owner all, üks transaktsioon faili kohta. See peab pearaamatut, <schema>.schema_migrations, iga faili kontrollsummaga; rakendatud fail, mille baidid on muutunud, lükatakse nimepidi tagasi (CHECKSUM_DRIFT), seda ei käivitata kunagi uuesti ega jäeta kunagi vahele. Iga ootel olev fail parsitakse enne esimese käivitamist tegeliku Postgresi grammatikaga, nii et tagasilükkamine jätab andmebaasi puutumata. Ainus päis, mida fail võib kanda, on -- nexus-migration: transaction=file|per-statement, valikuliste luku ja lause ajalõppudega; per-statement on mõeldud üksuse CREATE INDEX CONCURRENTLY jaoks.
Väravad
nexus-gates käivitab kakskümmend kaks vastavuskontrolli. Igaüks neist kodeerib ühe defektiklassi, et seda ei saaks kaks korda tarnida, ja igaühel on enesetest, mis tõestab, et see põrub testandmestikul (fixture), mis on ehitatud seda välja kutsuma. Käivitage need enne koodi üleslükkamist (push):
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test| Vastavuskontroll | Mida see püüab |
|---|---|
scope-adherence |
/api marsruut ilma skoobikaitseta; anonüümne asukoht, mis ei ole täpne deklareeritud asukoht; seadmemarsruut ilma seadmekaitseta või koos isikukaitsega selle kõrval |
one-fence |
Rentniku predikaat, mis on defineeritud kusagil mujal peale ühe kindla koha, sealhulgas käsitsi kirjutatud töökoha või loa piire (fence) |
sql-fence |
Lause, mis loeb või uuendab skoobitud tabelit ilma piirdeta, mis tahes FROM-, JOIN-, USING- või UPDATE-sihtmärgis |
migrations-are-scoped |
Tabel, millel puudub telg, rentnikuga algav liitvõti, rentnikku kandev võõrvõti või demoveerg |
migrations-commit-what-they-open |
Migratsioon, mille BEGIN arv ei ühti selle COMMIT ja ROLLBACK arvuga |
no-direct-compute |
Otsekutse mudeli pakkujale, mootorile, järjekorrale või töövoo hostile; edastuse URL-i teine lugeja |
no-credentials |
Mudeli pakkuja mandaat, mis on loetav hoidlas või keskkonnas |
crud-adherence |
Andmeid muutev marsruut, mille õiguste kontroll ei nimeta registris midagi |
blocked-backends |
Marsruut, mida ei teenindata, ei blokeerita nimepidi, ei lükata seadusega tagasi ega omata mujal |
every-test-runs |
Testid, milleni testiskripti mustriotsing (glob) kunagi ei ulatu |
tiles-are-invariant |
Rentnikust sõltumatu vahemällu salvestatud ühenduskoht (seam), mis loeb rentniku väärtust või jätab autentimise vahele |
api-contract |
Registreeritud marsruut, mida manifest ei deklareeri, või deklareeritud marsruut, mida kood kunagi ei registreeri |
rls-present |
Tabel ilma sunnitud reataseme turvalisuseta; SECURITY DEFINER funktsioon ilma fikseeritud parameetrita search_path |
no-set-config |
Plugina kood, mis seob rentniku seadistuse ise |
db-role-honest |
Päringu teekond, mis ühendub omaniku või migreerijana või küsib rolliatribuuti SUPERUSER või BYPASSRLS |
platform-clients |
SDK klient, mis on imporditud, kuid pole loetletud üksuses backend.platformClients, või on loetletud, kuid pole kunagi imporditud |
rights-register |
Skoobimarsruut ilma deklareeritud õiguseta; õiguste kontroll registri kõrval |
refusal-ledger |
Deklareeritud keeldumiste tabel ilma paigaldatud pearaamatuta või keeldumise keha, mis on saadetud sellest mööda |
grants-declared |
Loaga tabel, mida manifest ei deklareeri; käsitsi välja jagatud lugemistöökoha privileegid |
people-declared |
people plokk ilma oma puhastusmarsruudi (sweep route), kaitse ja tabeliteta |
functions-closure |
Azure Functionsi plugin, mille teenindatavad marsruudid ja deklareeritud marsruudid ei ühti |
declared-input |
Käsitleja (handler) päringuparameetrite nimekiri, mis ei ühti marsruudi deklareeritud omadusega query |
Kataloog gates/ hoiab viit erandifaili, mida vastavuskontroll võib lugeda (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json ja invariant-seams.json), üks põhjus kirje kohta. Tühi põhjus loetakse kirje puudumiseks ja kirje, mis nimetab midagi, mida enam ei eksisteeri, nurjab vastavuskontrolli. Võite sinna lisada ka oma vastavuskontrolli mooduleid ja nexus-gates võtab need sisseehitatud kontrollide kõrval kasutusele.
Malli konveier (pipeline)
Mall ei tarni käsitsi kirjutatud töövoogu. Selle konveieri konfiguratsioon nimetab Dockerfile'i, ühe ehitusargumendi (registriloa), migratsiooni proovikäivituse ja käivitussondi ning vastavuskontrolli, mida mestimisjärjekord (merge queue) käivitab. Järjekord on selline, milles te sooviksitegi tõrkeid näha.
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest, mis oncreate-nexus-plugin validate nexus.manifest.jsonnpm run gates, mis onnexus-gates --self-testnode scripts/ci/required-env
Tõmmise ümber käivitatakse veel kaks kontrolli. Migratsiooni proovikäivitus rakendab iga faili ühekordsele Postgres-andmebaasile enne, kui tõmmise saab välja anda, kasutades sama käivitajat nagu toodangus: nexus-migrate provision üks kord superkasutajana, seejärel iga nummerdatud fail migreerijana. Alglaadimise kontroll käivitab ehitatud tõmmise selle enda sisenemispunktiga ja iga muutujaga, mille required-env väljastab, suunatuna asendustele, mis võtavad ühendusi vastu ega vasta kunagi. Server ootab andmebaasi oma piiratud ajaakna sees ja see ootamine on läbimise signaal; seadistuste laadija, mis keeldub alglaadimisest, kukutab ehituse läbi seal, mitte toodangus.
Mis see maksab
SDK teeb otsused teie eest ära ja mõne neist oleksite teinud teisiti. Manifest keeldub tundmatutest võtmetest, marsruuditabel peab täpselt vastama teie koodile, andmebaasi rollid ei ole teie kujundada ja kontrollväravad kukutavad ehituse läbi lugemisõiguse puudumise tõttu. Oma esimese pistikprogrammi puhul veetsin päeva, vaieldes tööriistaga api-contract marsruudi üle, mille olin registreerinud ja unustanud deklareerida. Sel oli õigus; marsruut oli kaitsmata. Arvestage sellega, et esimene pistikprogramm tundub aeglane ja teine võtab kolmandiku sellest ajast.

