InnskráningBóka kynningu

Kafli 2.21

Viðbóta-SDK

Uppsetning á viðbóta-SDK (þróunarsetti), skipanalínuverkfærum þess, kynningarferð um fullbúna sniðmátið, v2-yfirlýsingaskrána reit fyrir reit, og hliðin tuttugu og tvö sem halda viðbót innan reglnanna.

Þessi síða var þýdd með gervigreind úr enska frumtextanum. Ef eitthvað er óljóst gildir enska síðan til viðmiðunar. Lesa þessa síðu á ensku

22 mínútna lestur

Önnur viðbótin mín tók þriðjung þess tíma sem sú fyrsta tók, og nánast allur sparnaðurinn var SDK-inu (hugbúnaðarþróunarsetti) að þakka. Í fyrra skiptið skrifaði ég umfangsathugun, stillingahleðslu og flutningskeyrslu, og yfirlesari sendi hverja einustu þeirra til baka. Í seinna skiptið keyrði ég eina grunnsmíðaskipun, eyddi sýnifærninni fyrir tilfinningagreiningu og varði dögunum í frávikayfirferðarfærslurnar sem flugaflfræðiteymið okkar þurfti í raun.

@adverant-nexus/plugin-sdk er einn npm-pakki. Hann geymir v2-skilgreiningarskema upplýsingaskrárinnar og sannprófarana sem lesa það (definePlugin, defineSkill), keyrslueiningarnar sem viðbótin þín flytur inn fyrir umfang, gagnagrunn, sendingu og fleira, prófunarhjálpartól, fylgnihliðin og skipanalínutólin. Í þessum kafla er fjallað um uppsetningu hans, tólin, sniðmátið, upplýsingaskrána og hliðin. Kafli 2.22, Keyrsluumhverfi viðbóta, fjallar um keyrslueiningarnar í keyrandi kóða þínum.

Uppsetning þess

Pakkinn kemur úr skráasafni Adverant á https://registry.adverant.ai/npm/, aldrei úr opinbera npm-skráasafninu, og þú þarft sóttartáknið af síðunni „Pull tokens and install commands“ á reikningnum þínum. Beindu @adverant-nexus-umfanginu að skráasafninu í .npmrc geymslunnar þinnar:

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

<pull-token> er táknið af reikningssíðunni þinni. Í ferli skaltu senda það inn úr leyndarmáli og aldrei vista það í útgáfustýringu; Dockerfile sniðmátsins neitar að smíða án þess og eyðir .npmrc úr smíðastiginu þegar npm ci hefur keyrt, svo táknið fylgir aldrei með í mynd.

Festu síðan útgáfuna nákvæmlega:

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

Vistaðu package-lock.json í útgáfustýringu við fyrstu uppsetningu. Myndsmíði sniðmátsins keyrir npm ci og neitar að falla aftur á npm install: læsingarskráin er samningurinn. Lágmark SDK-sins sjálfs er Node 18; sniðmátið miðar á Node 20.

Skipanalínutólin fylgja pakkanum, svo hver skipun í þessum gögnum tilgreinir pakkann og útgáfu hans með npx -p. Eitt og sér er npx create-nexus-plugin flett upp í opinbera skráasafninu, og það heiti er ekki þessi pakki.

Skipanalínuverkfærin

Tól Hvað hann gerir
create-nexus-plugin Býr til grunn viðbótar, sannprófar upplýsingaskrá, flytur v1-upplýsingaskrá yfir í v2 og útbýr notendaleiðbeiningarnar fyrir framendaforritarann þinn
nexus-tenancy Útbýr leigjenda-SQL skemans þíns út frá upplýsingaskránni: hlutverk, heimildir, sniðmát raðöryggis og graftöflurnar
nexus-migrate Keyrir flutningana þína: útvegar hlutverkin einu sinni og keyrir síðan hverja númeraða skrá sem flutningshlutverkið
nexus-gates Keyrir öll fylgnihlið og sjálfsprófun hvers hliðs

create-nexus-plugin framkvæmir ekkert netkall og hleður engum fjarkóða. Það keyrir sömu innanferlissannprófara og innleiðing verkvangsins keyrir, svo ekkert misræmi verður á milli „það stóðst sannprófun hjá mér“ og „verkvangurinn samþykkti það“.

Aðgerð Flögg Hvað hann gerir Útgöngukóðar
scaffold <name> --tier full-service\|ui-only\|skills-only, --dir <path>, --print Skrifar nýja viðbótarmöppu; --print prentar aðeins upplýsingaskrána 0 skrifað · 1 neitaði að yfirskrifa · 2 röng notkun
validate <file> Sannprófar nexus.manifest.json, eða .ts- eða .js-einingu sem flytur hana út 0 gilt · 1 ógilt eða ólæsilegt · 2 röng notkun
migrate <file> --write Lyftir v1-upplýsingaskrá upp í v2 og prentar hana, eða skrifar hana á sama stað 0 · 1 · 2, eins og að ofan
guide --manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint Útbýr notendaleiðbeiningarnar úr upplýsingaskránni og frásögn þinni; --check ber saman við vistaða eintakið og skrifar ekkert 0 · 1 misræmi eða brot í lintun · 2 röng notkun
help Prentar notkunarleiðbeiningar 0

Grunngerð og þrepin þrjú

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

--tier er sjálfgefið full-service. Grunnsmiðurinn neitar að skrifa í möppu sem er þegar til, og upplýsingaskráin sem hann skrifar stenst þegar sannprófun; hann skilar aldrei ógildri.

Veldu stigið eftir því hvað viðbótin þín inniheldur.

Þrep Inniheldur Verður að skilgreina
skills-only Færni í upplýsingaskrá og ekkert annað skills[], með að minnsta kosti einni færslu
ui-only Framendaviðmót innan skeljarinnar frontend
full-service Bakenda og framenda, yfirleitt með eigið skema backend og frontend; og þar sem hún hefur bakenda, runtime.healthCheck

Ef þú ert ekki viss skaltu búa til grunn með full-service og eyða því sem þú þarft ekki. Að fara hina leiðina þýðir að skrifa þá hluta sem sniðmátið hefði gefið þér.

Kynningarferð um fullbúna sniðmátið

Sniðmátið er viðmiðunarviðbótin, smíðuð eftir hinu stranga mynstri sem allir síðari kaflar gera ráð fyrir. Afritaðu lögun hennar, ekki sýnirökfræði hennar.

Slóð Hvað það er
nexus.manifest.json v2-upplýsingaskráin: lögin þrjú endurorðuð, leiðatöflan og réttindaskrá hennar
src/config.ts Stillingahleðslan. Ein forskrift, lesin einu sinni, öllum vandamálum safnað saman áður en ferlið neitar að ræsa
src/scope.ts Eina skráin sem breytir beiðni í umfang, með ströngum táknsannprófara SDK-sins og tveimur fyrirkomulögum: handhafatákni einstaklings og þjónustukalli verkvangsins
src/db.ts Hver skipun setur saman tenantFence() og keyrir innan withScopedTx
src/uno.ts Eina sendingarskráin: ein vefslóð, einn biðlari, lokaður leyfislisti
src/routes/*.ts health (nafnlaust, nákvæm slóð), /api-leiðirnar (með umfangi) og /internal-bakkallið (varið sem þjónusta)
src/skills/sentiment.ts Ákvarðanleg host_callback-færni; skiptu orðasafninu út fyrir eigin rökfræði
src/server.ts Samsetningarrótin: setur upp synjunarskrána einu sinni, bíður eftir gagnagrunninum (með tímamörkum) og keyrir síðan einangrunar- og skráarathuganirnar áður en hún hlustar
migrations/000_tenancy.sql Útbúið af nexus-tenancy render við grunnsmíði: hlutverk, skema, sniðmát raðöryggis
migrations/001_init.sql Tvær töflur með samsettum lykli sem hefst á leigjanda og samsettum ytri lykli sem ber leigjandann
migrations/002_refusal_ledger.sql Taflan sem synjunarskráin skrifar í
scripts/ci/required-env Prentar heiti umhverfisbreytanna sem ræsing krefst sem JSON
scripts/ci/shadow-migrate-*.sh Prufukeyrsla ferlisins á flutningum, í gegnum nexus-migrate
gates/ Undanþágumappa hliðanna: tóm, sem er rétt staða fyrir nýja viðbót
test/ Prófanir fyrir umfang, leiðir, gagnagrunn, sendingu og ræsingu, með umfangsstaðgenglunum sem hver prófun fær innsetta
Dockerfile Mynd sem keyrir ekki sem rót (notandakenni 10001) með flutningana innanborðs

Nokkrar þessara skráa eru þess virði að skoða nánar.

src/config.ts fylgir tveimur reglum. Hún safnar öllum vandamálum saman áður en hún kastar villu, svo ein endurræsing nefnir allar fimm breyturnar sem vantar í stað fimm endurræsinga sem nefna eina hver. Og hún gefur gildi sjálfgefið aðeins þegar rangt gildi getur ekki leitt til hljóðlauss rangs svars: PORT má vera sjálfgefið 8080, því röng gátt veldur sýnilegri villu við bindingu, en DATABASE_URL og UNO_DISPATCH_URL eru áskilin og verða að vera vistföng innan klasans. Opinberu vistfangi er hafnað við ræsingu.

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

Eigin prófun sniðmátsins keyrir þá skrá og ber úttak hennar saman við heitin sem stillingaforskriftin merkir sem áskilin, svo ef áskilinni breytu er bætt við án þess að uppfæra listann bregst npm test.

src/server.ts hlustar ekki fyrr en gagnagrunnurinn svarar og takmarkar biðina við 120 sekúndur, þar sem hver misheppnuð tilraun er skráð ásamt orsök sinni. Síðan sannar hún, í þessari röð, að forritshlutverkið geti ekki endurbundið leigjandann og að allar töflur séu þvingaðar undir raðöryggi, að tengingasafn hvers pods rúmist innan tengingamarka hlutverksins og að tafla synjunarskrárinnar geti tekið við röð. Synjun frá einhverri þessara þriggja er prentuð í heild sinni og ferlið hættir með 2.

v2-yfirlýsingaskráin, reit fyrir reit

Upplýsingaskráin er véllesanlegur samningur viðbótarinnar við verkvanginn. Hún er sannprófuð þegar þú semur hana, þegar verkvangurinn innleiðir hana og stöðugt eftir það. Skemað er additionalProperties: false á öllum stigum: ef viðbótin þín hefur hluta er til eiginleiki fyrir hann, og óskilgreindum lykli er hafnað. Lausnin er alltaf að nota rétta valfrjálsa eiginleikann.

Áskilinn kjarni

Reitur Regla
manifestVersion Nákvæmlega "2". v1-skjal er flutt, aldrei endursannprófað á sama stað
name ^[a-z0-9]+([-.][a-z0-9]+)*$, að hámarki 64 stafir. Auðkenni viðbótarinnar sem notað er við skráningu, nafnasvæði sendinga og raðir bundnar leigjanda. Viðbót sem skilgreinir færni þarf einnig heiti án punkts og án tölustafs í upphafi
displayName 1 til 120 stafir
version Merkingarbær útgáfa; þín eigin útgáfuröð
description, author, license Að minnsta kosti einn stafur hvert
tier skills-only, ui-only eða full-service
trust core, verified, community eða untrusted
runtime Áskilið: executionMode, isolationLevel (1 til 4), entrypoint. Valfrjálst: nodeVersion, healthCheck, readinessCheck, livenessCheck, hvert slóð sem hefst á /. Hátturinn ræðst af stiginu: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker
architecture compute, ai og deploy, lög verkvangsins þrjú endurorðuð. Sannprófarinn festir orðalagið

Fyrir viðbót sem þú smíðar fyrir eigin uppsetningu hljóða setningarnar þrjár svona. ai-setningin fjallar um gervigreind og er staðurinn til að taka fram að viðbótin geymi engin auðkenni líkana.

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

Leiðataflan: api og rights

api þarf version og basePath, og valfrjálst websocket (path, auth) og endpoints[]. Leiðataflan er sterkasta hugmyndin í skemanu: hlið ber hana saman við leiðirnar sem kóðinn þinn skráir í raun, í báðar áttir, svo upplýsingaskráin er sannreynanlegur samningur en ekki skjölun.

Hver endapunktur þarf method (GET, POST, PUT, PATCH eða DELETE) og path. Afgangurinn:

Reitur Hvað stendur í því
auth Einn af fimm flokkum: scope (leið einstaklings, á bak við umfangsvörðinn), service-key og internal (netþjónn til netþjóns, aldrei aðgengilegt úr vafra), public (alltaf aðeins nákvæm slóð með allowAnonymous) og device (vél með eigin auðkenni, á bak við tækjavörðinn)
right Áskilið á hverri leið sem umfangsvörðurinn þjónar og hafnað á öllum öðrum: heiti réttinda í rights-skránni
needsUnit Leiðin synjar þegar ekki er hægt að ákvarða einingu kallandans
allowAnonymous Eingöngu leyfislisti með nákvæmri samsvörun. Forskeytisregla er leiðin til þess að /health-of-tenant-42 endar opinbert
group, serves, screens Undir release-blokk: getuflokkurinn sem leiðin þjónar, hverju hún svarar þegar leyfisskyldur eiginleiki þess flokks er læstur (data, teaser, sighting eða ask), og skjámyndirnar sem hún þjónar
query required (hvert heiti með dæmigildi) og allowed: fyrirspurnarfæribreyturnar sem leiðin les
body example: dæmi um meginmál ritunarleiðar, sem hennar eigin sannprófari samþykkir. Aldrei á GET

rights er skráin sem þessar leiðir vísa í. Hver réttindi hafa roles (þakið) og valfrjálst summary, never (hlutverk sem mega aldrei beita þeim, hvað sem þau hafa annað), barred (eigin orð vörunnar til að synja never-hlutverki), seat (virkt sæti þarf líka), self (allir staðfestir einstaklingar hafa þau, fyrir réttindi yfir eigin lotu), grants (handhafar úthluta sætum; í mesta lagi ein réttindi segja það), licence (leyfisskyldur eiginleiki sem leyfi fyrirtækisins verður að innihalda) installation (aðeins í höndum eigin stjórnenda uppsetningarinnar) og platform (aðeins í höndum verkvangsstjórnenda Adverant; nefnir engin hlutverk). Heiti réttinda innihalda að minnsta kosti einn 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 hafnar umfangsleið án réttinda (ENDPOINT_RIGHT_MISSING), réttindum sem skrána vantar (ENDPOINT_RIGHT_NOT_REGISTERED) og réttindum á leið sem enginn vörður þjónar (ENDPOINT_RIGHT_UNGUARDED). Það hafnar einnig skrá sem stangast á við sjálfa sig, og tveimur ritháttum einnar leiðar (:id og :recordId) sem DUPLICATE_ENDPOINT.

Gögnin þín: databases, schema og db

schema er eina Postgres-skemað sem viðbótin á. public, plugins, auth og nexus eru bönnuð, og ef databases[] nefnir einnig Postgres-skema verða þau tvö að passa saman.

databases[] skilgreinir hverja geymslu eftir vél: postgresql (schema, tables, migrations og granted, töflurnar sem annað fyrirtæki má lesa samkvæmt skráðri heimild), neo4j (schemas), qdrant (collections) eða redis (purpose).

db geymir lotumörkin fyrir allar tengingar sem viðbótin opnar, skilgreind hér frekar en kóðuð svo bæði yfirlesari og uppsetningin geti lesið þau:

Reitur Hvað það takmarkar
maxConnections Tengingasafnið á hvert afrit
pods Mesti fjöldi podda sem hafa tengingasafn samtímis, afrit auk aukningar við rúllandi uppfærslu. Tengingamörk hvers hlutverks eru útbúin sem maxConnections × pods; ef þú sleppir þessu varar definePlugin við DB_PODS_UNDECLARED
statementTimeoutMs Ein skipun
idleInTransactionTimeoutMs Opin færsla sem keyrir ekkert
workMemKB Einn röðunar- eða tætihnútur, á hvern hnút, ekki á hverja fyrirspurn
piiMask[] table.column-færslur sem geyma persónuupplýsingar, huldar í stýrðu SQL-stjórnborðinu og í annálum

Færni og tól: skills, mcpTools, entitlements

skills[] geymir færni upplýsingaskrárinnar; kafli 2.20, Færni, fjallar um svið hennar og stig. mcpTools[] geymir MCP-tólin (Model Context Protocol) sem viðbótin birtir, hvert með name, description og inputSchema án oneOf, allOf eða anyOf á efsta stigi.

entitlements krefst featureIdPattern og tekur við alwaysOn[], source og store. Mynstrið tilgreinir nafnasvæðið sem auðkenni eiginleika þinna eru í, venjulega name viðbótarinnar auk eins hluta sem kóðinn þinn fyllir út fyrir hvert viðmót. alwaysOn[] er stutti, nákvæmi listinn sem verður að svara jafnvel þegar enginn úrskurður um réttindi fæst: heilbrigði, reiðubúni, innskráning og stillingarnar sem stjórnandi þarf til að lagfæra réttindin.

Breytingastjórnun: changePolicy

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

Samþykki eru talin í aðskildum einstaklingum, og sá sem lagði breytinguna til er aldrei einn þeirra; án beggja helminganna verða „tvö samþykki“ að einum einstaklingi sem smellir tvisvar. enabled: true krefst classes, og hver flokkur sem er nefndur þarf eigin fjölda. Flokkur sem þú sleppir er óstýrður, sem er lögmætt val sem skemað lætur þig skrá niður.

Hver þú ert: domains, branding, routing

domains[] (hvert primary og aliases[]; domain er form fyrir eitt lén) tilgreinir hvar viðbótin svarar. branding krefst appName og tekur við tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId og gaId. Allt í branding er opinbert: innskráningarsíðan les það áður en nokkur hefur auðkenni, svo það geymir aldrei leyndarmál eða innra vistfang. routing (type, gateway, virtualService) er fyrir viðbætur sem lýsa eigin leiðavali.

Stærðarval og annað

resources krefst cpuMillicores (10 til 64,000) og memoryMB (16 til 262,144) og tekur við diskGB, timeoutMs, port og wsPort. backend geymir port, healthPath, apiPrefix, framework og platformClients[], SDK-biðlarana sem bakendinn yðar flytur inn eftir nafni. Listinn er lokaður og hlið ber hann saman við innflutninga yðar. Skemað leyfir fjórtán nöfn: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin og uno, auk eins fyrir biðlarann sem svarar synjunum um áskriftarréttindi, sem heldur innra nafni. Biðlarinn fyrir eiginleikaréttindi, runtime/entitlements, er ekki einn þeirra og fer aldrei á listann, því að entitlements-blokkin yðar lýsir honum þegar yfir, og bakendi sem flytur hann inn án entitlements-blokkar fellur á sama hliði. frontend geymir basePath, mountPath og framework. nexus geymir minVersion, maxVersion, capabilities[] og permissions[].

Hver hinna blokkanna er til staðar fyrir eitt verk:

Blokk Til hvers
settings Stillingar yðar á sameiginlega rammanum: groups og keys, stilltar á þeim stigum sem hvor tilgreinir
people sweep (service, port): meðlimir fyrirtækisins, samstilltir frá auðkennisþjónustunni, þar sem slökkt er á sætum þegar einhver hættir
ontology entityTypes og relationshipTypes: tegundabundna grafið sem geymt er í yðar eigin skema
release groups og frame: getuhóparnir sem leiðir yðar eru settar upp í, gefnir fyrst út sem kanarí-útgáfa
cells[] Viðbót sem samanstendur af nokkrum uppsetningareiningum: name, kind, entrypoint, port, wsPort fyrir hverja
pricing model, currency, tiers[] fyrir skráningu yðar í vörulistanum
marketplace category, icon, screenshots, documentation, featured
compliance instruments[], dataResidency, sovereignty
developer, repository, keywords Hver gefur hana út og hvar kóði hennar er geymdur
metrics, atlas Hlutirnir tveir sem eru vísvitandi opnir, fyrir yðar eigin mælikvarðanöfn og gerð arkitektúrsskjala

Það sem skemað getur ekki tjáð

JSON Schema ákvarðar lögun; definePlugin bætir við reglunum sem skema getur ekki tjáð. classification færni má ekki fara yfir traustþakið. Aðeins core- og verified-viðbætur mega lýsa yfir tool_using- og llm_only-færni. Sérhver yfirlýst slóð verður að vera afstæð og af sama uppruna, án skema, án // og án öfugs skástriks, því að URL-þáttarinn breytir \ í / og /\evil.example/x vísar á annan uppruna. Sérhver regla sem samstilling skrárinnar beitir á færni er beitt hér fyrst, með kóða samstillingarinnar sjálfrar, svo að validate og samstillingin nefna brotna reglu á sama hátt.

Sannprófun og færsla úr 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

Villa prentar nákvæma slóð og, fyrir samstillingarreglu, kóðann fyrst. Gerið þetta að commit-krók.

Hægt er að lyfta v1-skilgreiningarskrá vélrænt. migrate bætir við lagasetningunum þremur, færir domain í domains[] og neitar að búa til inngangspunkt sem þér höfðuð ekki. Hún staðfestir niðurstöðuna áður en hún prentar eða skrifar nokkuð, svo að flutningur færir aldrei villu úr tólinu inn í gagnageymslu yðar.

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

Lesið mismuninn áður en þér framið hann. Lagasetningarnar sem bætt er við eru orðalagið sem staðfestingartólið festir; fyrir yðar eigin uppsetningu skuluð þér stilla deploy á setninguna sem sýnd var fyrr.

Framsetning leigueiningar og úthlutun hlutverka

Þér skrifið aldrei hlutverkaheimildir yðar eða sniðmátið fyrir öryggi á línustigi í höndunum. nexus-tenancy render skrifar þau út frá schema og db í skilgreiningarskránni:

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

Myndaða skráin býr til fimm hlutverk fyrir skemað, hvert með því sem það má ekki hafa: flutningshlutverk sem getur aðeins orðið eigandinn, eiganda sem getur ekki skráð sig inn, forritshlutverk fyrir beiðnaslóðina, skýrsluhlutverk sem sér aðeins samantektir og bókhaldshlutverk sem getur aðeins bætt við. Ekkert hlutverk hefur BYPASSRLS. Eina leiðin til að binda leigjanda er eitt gagnagrunnsfall og set_config er afturkallað frá öllum hlutverkum nema eigandanum.

Leigjendaskrá sem hefur verið beitt er aldrei breytt. Breyting er endurskoðun með eigin skrá númer 0, og lessætið fyrir heimildir milli fyrirtækja kemur á þann hátt, sem endurskoðun 2. --graph myndar töflurnar tvær í tegundabundna grafinu sem ontology yðar lýsir yfir sem næsta númeraða flutning yðar.

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

Leigjendaskráin býr til einmitt þau hlutverk sem keyrslutólið tengist sem, svo að eigandi gagnagrunnsins beitir henni með 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> er tengistrengur fyrir eiganda gagnagrunnsins og <dir> er einkamappa. Úthlutun beitir grunnleigjendaskránni og öllum endurskoðunum í röð, skrifar migrator.url og app.url (og seat.url þegar endurskoðun 2 er til) í <dir> með ham 0600 og prentar ekkert leyndarmál. Hún stillir tengingamörk hvers hlutverks út frá db.maxConnections × db.pods við hverja keyrslu. Endurkeyrsla heldur núverandi lykilorðum nema þér biðjið um annað: --passwords <dir> stillir þau úr skrám og --rotate <roles> gefur tilgreindum hlutverkum ný. Gerið skrárnar að leyndarmálum uppsetningar yðar.

Eftir það tengist beiting með tengistreng flutningshlutverksins sem úthlutunin skrifaði:

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

Hún keyrir skrár frá 001 og áfram sem flutningshlutverkið, allar skrár undir SET ROLE <schema>_owner, eina færslu á hverja skrá. Hún heldur bókhald, <schema>.schema_migrations, með gátsummu hverrar skrár; beittri skrá þar sem bætin hafa breyst er hafnað eftir nafni (CHECKSUM_DRIFT), hún aldrei endurkeyrð og aldrei sleppt. Sérhver skrá í bið er þáttuð með raunverulegri Postgres-málfræði áður en sú fyrsta keyrir, svo að höfnun skilur gagnagrunninn eftir ósnertan. Eini hausinn sem skrá má bera er -- nexus-migration: transaction=file|per-statement, með valfrjálsum tímamörkum fyrir læsingu og skipun; per-statement er fyrir CREATE INDEX CONCURRENTLY.

Hliðin

nexus-gates keyrir tuttugu og tvö hlið. Hvert þeirra kóðar einn flokk galla svo að hann komist ekki tvisvar í útgáfu, og hvert hefur sjálfprófun sem sannar að það falli á prófunargögnum sem eru smíðuð til að fella það. Keyrið þau áður en þér ýtið:

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test
Hlið Hvað það grípur
scope-adherence /api-leið án umfangsvarðarins; nafnlaus slóð sem er ekki nákvæmlega yfirlýst; tækjaleið án tækjavarðarins, eða með varðar einstaklings við hlið hans
one-fence Leigjendaskilyrði sem er skilgreint annars staðar en á einum stað, þar á meðal handgerð sæta- eða heimildagirðing
sql-fence Skipun sem les eða uppfærir umfangsbundna töflu án girðingarinnar, í hvaða FROM-, JOIN-, USING- eða UPDATE-markmiði sem er
migrations-are-scoped Tafla sem vantar ás, samsettan lykil með leigjanda fremst, ytri lykil sem ber leigjanda eða sýnidálkinn
migrations-commit-what-they-open Flutningur þar sem fjöldi BEGIN passar ekki við fjölda COMMIT og ROLLBACK
no-direct-compute Beint kall í líkanaveitu, vél, biðröð eða verkflæðishýsil; annar lesandi sendingarslóðarinnar
no-credentials Auðkenni líkanaveitu sem er læsilegt í gagnageymslunni eða umhverfinu
crud-adherence Breytandi leið þar sem réttindaprófunin nefnir ekkert í skránni
blocked-backends Leið sem hvorki er þjónustuð, lokað eftir nafni, hafnað samkvæmt lögum né í eigu annars staðar
every-test-runs Prófanir sem glob prófunarskriftunnar nær aldrei til
tiles-are-invariant Leigjendaóháð skyndiminnissamskeyti sem les gildi leigjanda eða sleppir auðkenningu
api-contract Skráð leið sem skilgreiningarskráin lýsir ekki yfir, eða yfirlýst leið sem kóðinn skráir aldrei
rls-present Tafla án þvingaðs öryggis á línustigi; SECURITY DEFINER-fall án festrar search_path
no-set-config Viðbótarkóði sem bindur leigjandastillinguna sjálfur
db-role-honest Beiðnaslóð sem tengist sem eigandi eða flutningshlutverk, eða biður um SUPERUSER eða BYPASSRLS
platform-clients SDK-biðlari sem er fluttur inn en ekki skráður í backend.platformClients, eða skráður en aldrei fluttur inn
rights-register Umfangsleið án yfirlýsts réttar; réttindaprófun við hlið skrárinnar
refusal-ledger Yfirlýst höfnunartafla án uppsetts bókhalds, eða höfnunarmeginmál sent fram hjá því
grants-declared Heimiluð tafla sem skilgreiningarskráin lýsir ekki yfir; lessætisréttindi veitt í höndunum
people-declared people-blokk án hreinsunarleiðar sinnar, varðar og taflna
functions-closure Azure Functions-viðbót þar sem þjónustaðar leiðir og yfirlýstar leiðir stangast á
declared-input Listi fyrirspurnarbreyta meðhöndlara sem passar ekki við yfirlýst query leiðarinnar

gates/-mappan geymir undanþáguskrárnar fimm sem hlið má lesa (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json og invariant-seams.json), eina ástæðu á hverja færslu. Auð ástæða telst engin færsla, og færsla sem nefnir eitthvað sem er ekki lengur til fellir hliðið. Þér getið einnig sett yðar eigin hliðaeiningar þar og nexus-gates tekur þær upp við hlið innbyggðu eininganna.

Samhæfni
Samhæfni
Samhæfni sýnir hvaða SDK-útgáfa virkar með hvaða útgáfu verkvangsins, út frá næturkeyrslum flýtileiðbeininganna. Óprófað par segir það, og par sem fellur nefnir breytinguna sem braut það.

Keyrsluferli sniðmátsins

Sniðmátið fylgir ekkert handskrifað verkflæði. Leiðslustillingar þess nefna Dockerfile-skrána, einu byggingarbreytuna (aðgangslykil skrárinnar), prufukeyrslu flutninga og ræsingarprófunina, og hliðið sem samrunabiðröðin keyrir. Röðin er sú röð sem þér vilduð að villur kæmu fram í.

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

Tvær athuganir til viðbótar keyra í kringum myndina. Prufuflutningurinn keyrir hverja skrá á einnota Postgres áður en hægt er að gefa myndina út, með sama keyrsluforriti og raunumhverfið notar: nexus-migrate provision einu sinni sem ofurnotandi, og síðan hverja númeraða skrá sem flutningsnotandi. Ræsiskanninn ræsir smíðuðu myndina með sínum eigin inngangspunkti og öllum breytum sem required-env prentar út, og beinir henni að staðgenglum sem taka við tengingum en svara aldrei. Þjónninn bíður eftir gagnagrunninum, innan sinna skilgreindu tímamarka, og sú bið er merki um að prófið hafi tekist; stillingahleðslutæki sem neitar að ræsa sig fellir smíðina þar en ekki í raunumhverfi.

Smíðað á Community
Smíðað á Community
Á Community fær forritari sömu gullnu leiðirnar, þróunarsvæði og gagnagreinar á einum þjóni, með kóða í sinni eigin Git-hýsingu. Prófunarumhverfi, tilraunaeiningar og dulbúin afrit af raungögnum fylgja með Enterprise.

Hvað það kostar

SDK-pakkinn tekur ákvarðanirnar af þér, og sumar þeirra hefðir þú tekið öðruvísi. Yfirlýsingaskráin hafnar lyklum sem hún þekkir ekki, leiðataflan verður að passa nákvæmlega við kóðann þinn, hlutverk gagnagrunnsins eru ekki þín til að hanna og hliðin fella smíði ef réttindi vantar á lestur. Við gerð fyrstu viðbótarinnar minnar eyddi ég heilum degi í að þræta við api-contract um leið sem ég hafði skráð en gleymt að lýsa yfir. Það hafði rétt fyrir sér; leiðin var óvarin. Búist við að fyrsta viðbótin virki hægfara, og búist við að sú næsta taki þriðjung af tímanum.