Kirjaudu sisäänVaraa esittely

Luku 2.21

Plugin SDK

Plugin SDK -ohjelmistokehityspaketin asentaminen, sen komentorivityökalut, täyden palvelun mallipohjan esittely, v2-manifesti kenttä kentältä sekä 22 porttia, jotka varmistavat, että lisäosa noudattaa sääntöjä.

Tämä sivu on käännetty tekoälyllä englanninkielisestä alkuperäistekstistä. Jos jokin kohta on epäselvä, englanninkielinen sivu on ensisijainen lähde. Lue tämä sivu englanniksi

22 minuutin lukuaika

Toinen lisäosani vei kolmanneksen ensimmäisen ajasta, ja lähes koko säästö tuli SDK:sta (ohjelmistokehityspaketti). Ensimmäisellä kerralla kirjoitin laajuustarkistuksen, konfiguraation lataajan ja migraatioiden suorittajan, ja katselmoija palautti jokaisen niistä. Toisella kerralla ajoin yhden rungonluontikomennon, poistin esimerkkinä olleen sentimenttitaidon ja käytin päiväni poikkeamien katselmointitietueisiin, joita lentodynamiikkatiimimme todella tarvitsi.

@adverant-nexus/plugin-sdk on yksi npm-paketti. Se sisältää v2-manifestin skeeman ja sitä lukevat validaattorit (definePlugin, defineSkill), ajonaikaiset moduulit, jotka lisäosanne tuo laajuutta, tietokantaa, välitystä ja muuta varten, testiapuvälineet, noudattamisportit sekä komentorivityökalut. Tämä luku käsittelee sen asentamista, työkaluja, mallipohjaa, manifestia ja portteja. Luku 2.22, Lisäosan ajonaikainen ympäristö, käsittelee ajonaikaisia moduuleja käynnissä olevassa koodissanne.

Asentaminen

Paketti tulee Adverantin rekisteristä osoitteessa https://registry.adverant.ai/npm/, ei koskaan julkisesta npm-rekisteristä, ja tarvitsette noutotunnisteen tilinne sivulta "Pull tokens and install commands". Ohjatkaa @adverant-nexus-laajuus rekisteriin tietovarastonne tiedostossa .npmrc:

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

<pull-token> on tilisivultanne saatu tunniste. Välittäkää se putkessa salaisuudesta älkääkä koskaan tallentako sitä versionhallintaan; mallipohjan Dockerfile kieltäytyy rakentamasta ilman sitä ja poistaa .npmrc:n rakennusvaiheesta, kun npm ci on suoritettu, joten tunniste ei koskaan päädy levykuvaan.

Kiinnittäkää sitten versio tarkasti:

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

Tallentakaa package-lock.json versionhallintaan ensimmäisen asennuksen yhteydessä. Mallipohjan levykuvan rakennus suorittaa npm ci:n eikä suostu palaamaan npm install:een: lukitustiedosto on sopimus. SDK:n oma vähimmäisvaatimus on Node 18; mallipohja on tehty Node 20:lle.

Komentorivityökalut toimitetaan paketin sisällä, joten jokainen tämän dokumentaation komento nimeää paketin ja sen version npx -p:llä. Pelkkä npx create-nexus-plugin haetaan julkisesta rekisteristä, eikä se nimi viittaa tähän pakettiin.

Komentorivityökalut

Työkalu Mitä se tekee
create-nexus-plugin Luo lisäosan rungon, validoi manifestin, siirtää v1-manifestin v2:een ja tuottaa käyttäjäoppaan frontend-kehittäjällenne
nexus-tenancy Tuottaa skeemanne vuokralaisuuden SQL:n manifestista: roolit, oikeudet, rivitason suojauksen mallin ja graafitaulut
nexus-migrate Ajaa migraationne: luo roolit kerran ja suorittaa sitten jokaisen numeroidun tiedoston migraattoriroolina
nexus-gates Ajaa jokaisen noudattamisportin ja kunkin portin oman itsetestin

create-nexus-plugin ei tee verkkokutsuja eikä lataa etäkoodia. Se ajaa samat prosessinsisäiset validaattorit kuin alustan käyttöönotto, joten "se validoitui omalla koneellani" ja "alusta hyväksyi sen" eivät voi erota toisistaan.

Komento Liput Mitä se tekee Paluukoodit
scaffold <name> --tier full-service\|ui-only\|skills-only, --dir <path>, --print Kirjoittaa uuden lisäosahakemiston; --print tulostaa vain manifestin 0 kirjoitettu · 1 kieltäytyi korvaamasta · 2 virheellinen käyttö
validate <file> Validoi nexus.manifest.json:n tai sellaisen vievän .ts- tai .js-moduulin 0 kelvollinen · 1 virheellinen tai lukukelvoton · 2 virheellinen käyttö
migrate <file> --write Nostaa v1-manifestin v2:een ja tulostaa sen tai kirjoittaa sen paikalleen 0 · 1 · 2, kuten yllä
guide --manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint Tuottaa käyttäjäoppaan manifestista ja kuvauksestanne; --check vertaa tallennettuun kopioon eikä kirjoita mitään 0 · 1 poikkeama tai lint-rikkomus · 2 virheellinen käyttö
help Tulostaa käyttöohjeen 0

Alustaminen (scaffolding) ja kolme tasoa

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

--tier:n oletusarvo on full-service. Rungonluoja kieltäytyy kirjoittamasta olemassa olevaan hakemistoon, ja sen kirjoittama manifest läpäisee jo validoinnin; se ei koskaan tuota virheellistä manifestia.

Valitkaa taso sen mukaan, mitä lisäosassanne on.

Taso Sisältää Täytyy määritellä
skills-only Vain manifestin taitoja skills[], jossa vähintään yksi merkintä
ui-only Frontend-näkymä kehyksen sisällä frontend
full-service Backend ja frontend, yleensä omalla skeemalla backend ja frontend; ja koska siinä on backend, runtime.healthCheck

Jos ette ole varma, luokaa runko full-service:llä ja poistakaa se, mitä ette tarvitse. Toiseen suuntaan eteneminen tarkoittaa niiden osien kirjoittamista, jotka mallipohja olisi antanut teille.

Täyden palvelun mallipohjan esittely

Mallipohja on viitelisäosa, joka on rakennettu tiukan mallin mukaan, jonka jokainen myöhempi luku olettaa. Kopioikaa sen rakenne, älkää sen esimerkkilogiikkaa.

Polku Mikä se on
nexus.manifest.json v2-manifest: kolme lakia uudelleen ilmaistuina, reittitaulukko ja sen oikeusrekisteri
src/config.ts Konfiguraation lataaja. Yksi määrittely, luetaan kerran, jokainen ongelma kerätään ennen kuin prosessi kieltäytyy käynnistymästä
src/scope.ts Ainoa tiedosto, joka muuttaa pyynnön laajuudeksi, SDK:n tiukalla tunnisteen tarkistimella ja kahdella käytännöllä: henkilön bearer-tunniste ja alustan palvelukutsu
src/db.ts Jokainen lause koostaa tenantFence():n ja suoritetaan withScopedTx:n sisällä
src/uno.ts Ainoa välitystiedosto: yksi URL, yksi asiakas, suljettu sallittujen luettelo
src/routes/*.ts health (anonyymi, tarkka polku), /api-reitit (laajuuteen sidotut) ja /internal-takaisinkutsu (palvelusuojattu)
src/skills/sentiment.ts Deterministinen host_callback-taito; korvatkaa sanasto omalla logiikallanne
src/server.ts Koostamisjuuri: asentaa kieltäytymiskirjanpidon kerran, odottaa tietokantaa (rajatusti) ja ajaa sitten eristys- ja kirjanpitotarkistukset ennen kuuntelun aloittamista
migrations/000_tenancy.sql nexus-tenancy render:n tuottama rungonluonnin yhteydessä: roolit, skeema, rivitason suojauksen malli
migrations/001_init.sql Kaksi taulua, joissa on vuokralaisella alkava yhdistelmäavain ja yhdistelmä-viiteavain, joka sisältää vuokralaisen
migrations/002_refusal_ledger.sql Taulu, johon kieltäytymiskirjanpito kirjoittaa
scripts/ci/required-env Tulostaa käynnistyksessä vaadittujen ympäristömuuttujien nimet JSON-muodossa
scripts/ci/shadow-migrate-*.sh Putken migraatioiden kuivaharjoitus nexus-migrate:n kautta
gates/ Porttien poikkeushakemisto: tyhjä, mikä on uuden lisäosan oikea tila
test/ Testit laajuudelle, reiteille, tietokannalle, välitykselle ja käynnistykselle sekä laajuuden testikorvikkeet, jotka jokainen testi injektoi
Dockerfile Ei-root-levykuva (käyttäjätunnus 10001), jonka sisällä ovat migraatiot

Muutama näistä tiedostoista ansaitsee tarkemman tarkastelun.

src/config.ts noudattaa kahta sääntöä. Se kerää jokaisen ongelman ennen poikkeuksen heittämistä, joten yksi uudelleenkäynnistys nimeää kaikki viisi puuttuvaa muuttujaa sen sijaan, että viisi uudelleenkäynnistystä nimeäisi kukin yhden. Ja se antaa arvolle oletuksen vain silloin, kun väärä arvo ei voi tuottaa hiljaista väärää vastausta: PORT:n oletus voi olla 8080, koska väärä portti saa sidonnan epäonnistumaan näkyvästi, kun taas DATABASE_URL ja UNO_DISPATCH_URL ovat pakollisia ja niiden on oltava klusterin sisäisiä osoitteita. Julkinen osoite hylätään käynnistyksessä.

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

Mallipohjan oma testi ajaa tämän tiedoston ja vertaa sen tulostetta nimiin, jotka konfiguraatiomäärittely merkitsee pakollisiksi, joten pakollisen muuttujan lisääminen päivittämättä luetteloa saa npm test:n epäonnistumaan.

src/server.ts ei aloita kuuntelua ennen kuin tietokanta vastaa, ja se rajaa odotuksen 120 sekuntiin ja kirjaa jokaisen epäonnistuneen yrityksen syineen. Sitten se todistaa järjestyksessä, että sovellusrooli ei voi sitoa vuokralaista uudelleen ja että jokainen taulu on pakotettu rivitason suojauksen alaiseksi, että kunkin podin yhteysallas mahtuu roolin yhteysrajaan ja että kieltäytymiskirjanpidon tauluun voi kirjoittaa rivin. Minkä tahansa näistä kolmesta hylkäys tulostetaan kokonaisuudessaan ja prosessi päättyy koodilla 2.

v2-manifesti kenttä kentältä

Manifest on lisäosan koneluettava sopimus alustan kanssa. Se validoidaan, kun laaditte sen, kun alusta ottaa sen käyttöön, ja jatkuvasti sen jälkeen. Skeema on additionalProperties: false jokaisella tasolla: jos lisäosassanne on osio, sille on ominaisuus, ja määrittelemätön avain hylätään. Korjaus on aina käyttää oikeaa valinnaista ominaisuutta.

Pakollinen ydin

Kenttä Sääntö
manifestVersion Täsmälleen "2". v1-dokumentti siirretään, sitä ei koskaan validoida uudelleen paikallaan
name ^[a-z0-9]+([-.][a-z0-9]+)*$, enintään 64 merkkiä. Lisäosan tunniste, jota käytetään rekisteröinnissä, välityksen nimiavaruuksissa ja vuokralaiskohtaisissa riveissä. Taitoja määrittelevä lisäosa tarvitsee lisäksi nimen, jossa ei ole pistettä eikä alussa numeroa
displayName 1–120 merkkiä
version Semanttinen versio; oma julkaisusyklinne
description, author, license Kukin vähintään yhden merkin mittainen
tier skills-only, ui-only tai full-service
trust core, verified, community tai untrusted
runtime Pakolliset: executionMode, isolationLevel (1–4), entrypoint. Valinnaiset: nodeVersion, healthCheck, readinessCheck, livenessCheck, kukin /-alkuinen polku. Tila johdetaan tasosta: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker
architecture compute, ai ja deploy, kolme alustan lakia uudelleen ilmaistuina. Validaattori lukitsee sanamuodon

Omaa asennustanne varten rakentamassanne lisäosassa nämä kolme lausetta kuuluvat seuraavasti. ai-lause koskee tekoälyä, ja siinä todetaan, ettei lisäosa sisällä mallien tunnistetietoja.

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

Reittitaulukko: api ja rights

api vaatii version:n ja basePath:n sekä valinnaisesti websocket:n (path, auth) ja endpoints[]:n. Reittitaulukko on skeeman vahvin ajatus: portti vertaa sitä reitteihin, jotka koodinne todella rekisteröi, molempiin suuntiin, joten manifest on tarkistettavissa oleva sopimus eikä dokumentaatiota.

Jokainen päätepiste tarvitsee method:n (GET, POST, PUT, PATCH tai DELETE) ja path:n. Loput:

Kenttä Mitä se kertoo
auth Yksi viidestä luokasta: scope (henkilön reitti, laajuusvartijan takana), service-key ja internal (palvelimelta palvelimelle, ei koskaan saavutettavissa selaimesta), public (aina vain tarkka polku allowAnonymous:n kanssa) ja device (kone, jolla on oma tunnistetietonsa, laitevartijan takana)
right Pakollinen jokaisella laajuusvartijan palvelemalla reitillä ja hylätään kaikilla muilla: rights-rekisterissä olevan oikeuden nimi
needsUnit Reitti hylkää pyynnön, kun kutsujan yksikköä ei voida selvittää
allowAnonymous Vain tarkkojen osumien sallittujen luettelo. Etuliitesääntö on tapa, jolla /health-of-tenant-42 päätyy julkiseksi
group, serves, screens release-lohkon alla: reitin palvelema kyvykkyysryhmä, mitä se vastaa, kun ryhmän lisensoitu ominaisuus on lukittu (data, teaser, sighting tai ask), ja sen palvelemat näkymät
query required (kukin nimi esimerkkiarvoineen) ja allowed: reitin lukemat kyselyparametrit
body example: kirjoitusreitin esimerkkirunko, jonka reitin oma validaattori hyväksyy. Ei koskaan GET-pyynnössä

rights on rekisteri, jonka nimiä nämä reitit käyttävät. Jokaisella oikeudella on roles (yläraja) ja valinnaisesti summary, never (roolit, jotka eivät saa koskaan käyttää sitä, riippumatta siitä, mitä muuta niillä on), barred (tuotteen omat sanat never-roolin torjumiseen), seat (tarvitaan myös aktiivinen käyttöpaikka), self (jokaisella vahvistetulla henkilöllä on se, oikeuksiin omaan istuntoon), grants (haltijat myöntävät käyttöpaikkoja; enintään yksi oikeus voi määritellä tämän), licence (lisensoitu ominaisuus, joka organisaation lisenssissä on oltava) installation (vain asennuksen omilla ylläpitäjillä) ja platform (vain Adverantin alustaylläpitäjillä; se ei nimeä rooleja). Oikeuksien nimissä on vähintään yksi piste: 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 hylkää laajuusreitin, jolla ei ole oikeutta (ENDPOINT_RIGHT_MISSING), oikeuden, jota rekisterissä ei ole (ENDPOINT_RIGHT_NOT_REGISTERED), ja oikeuden reitillä, jota mikään vartija ei palvele (ENDPOINT_RIGHT_UNGUARDED). Se hylkää myös itsensä kanssa ristiriitaisen rekisterin sekä saman reitin kaksi kirjoitusasua (:id ja :recordId) virheellä DUPLICATE_ENDPOINT.

Tietonne: databases, schema ja db

schema on se yksi Postgres-skeema, jonka lisäosa omistaa. public, plugins, auth ja nexus ovat kiellettyjä, ja jos databases[] nimeää myös Postgres-skeeman, niiden on vastattava toisiaan.

databases[] määrittelee jokaisen tietovaraston moottorin mukaan: postgresql (schema, tables, migrations ja granted, taulut, joita toinen organisaatio voi lukea kirjatun myönnön perusteella), neo4j (schemas), qdrant (collections) tai redis (purpose).

db sisältää istuntorajat jokaiselle lisäosan avaamalle yhteydelle, määriteltyinä tässä eikä koodattuina, jotta sekä katselmoija että käyttöönotto voivat lukea ne:

Kenttä Mitä se rajaa
maxConnections Yhteysallas replikaa kohden
pods Enimmäismäärä podeja, joilla on samanaikaisesti yhteysallas: replikat sekä liukuvan päivityksen ylitys. Kunkin roolin yhteysraja tuotetaan muodossa maxConnections × pods; jos jätätte sen pois, definePlugin varoittaa DB_PODS_UNDECLARED
statementTimeoutMs Yksi lause
idleInTransactionTimeoutMs Avoin transaktio, joka ei suorita mitään
workMemKB Yksi lajittelu- tai hajautussolmu, solmua kohden, ei kyselyä kohden
piiMask[] Henkilötietoja sisältävät table.column-merkinnät, jotka peitetään hallinnoidussa SQL-konsolissa ja lokeissa

Taidot ja työkalut: skills, mcpTools, entitlements

skills[] sisältää manifestin taidot; luku 2.20, Taidot, käsittelee niiden kenttiä ja tasoja. mcpTools[] sisältää lisäosan julkaisemat MCP (Model Context Protocol) -työkalut, kullakin name, description ja inputSchema ilman ylätason oneOf:ta, allOf:ää tai anyOf:aa.

entitlements vaatii featureIdPattern:n ja hyväksyy alwaysOn[]:n, source:n ja store:n. Kuvio nimeää nimiavaruuden, jossa ominaisuustunnisteenne ovat, tavallisesti lisäosan name sekä yksi osa, jonka koodinne täyttää näkymäkohtaisesti. alwaysOn[] on lyhyt, tarkka luettelo siitä, minkä on vastattava silloinkin, kun käyttöoikeuspäätöstä ei saada: kunto, valmius, sisäänkirjautuminen ja asetukset, joita ylläpitäjä tarvitsee käyttöoikeuden korjaamiseen.

Muutosten hallinta: changePolicy

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

Hyväksynnät lasketaan eri henkilöinä, eikä muutoksen ehdottanut henkilö ole koskaan yksi heistä; ilman molempia puolia "kaksi hyväksyntää" tarkoittaa yhtä henkilöä, joka napsauttaa kahdesti. enabled: true vaatii classes:n, ja jokainen nimetty luokka tarvitsee oman lukumääränsä. Pois jättämänne luokka on hallitsematon, mikä on oikeutettu valinta, jonka skeema saa teidät kirjaamaan.

Keitä olette: domains, branding, routing

domains[] (kukin primary ja aliases[]; domain on yhden verkkotunnuksen muoto) luettelee, missä lisäosa vastaa. branding vaatii appName:n ja hyväksyy tagline:n, logo:n, favicon:n, primaryColor:n, accentColor:n, oauthClientRef:n, passkeyRpId:n ja gaId:n. Kaikki branding:ssa on julkista: sisäänkirjautumissivu lukee sen ennen kuin kenelläkään on tunnistetietoja, joten siinä ei koskaan ole salaisuutta tai sisäistä osoitetta. routing (type, gateway, virtualService) on tarkoitettu lisäosille, jotka kuvaavat oman reitityksensä.

Mitoitus ja muut

resources edellyttää kenttiä cpuMillicores (10–64 000) ja memoryMB (16–262 144) ja hyväksyy kentät diskGB, timeoutMs, port ja wsPort. backend sisältää kentät port, healthPath, apiPrefix, framework ja platformClients[], eli SDK-asiakkaat, jotka taustajärjestelmänne tuo nimeltä. Luettelo on suljettu, ja tarkistus vertaa sitä tuonteihinne. Skeema sallii neljätoista nimeä: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin ja uno sekä yhden sille asiakkaalle, joka vastaa sopimusoikeuksiin perustuviin hylkäyksiin ja jolla on sisäinen nimi. Ominaisuusoikeuksien asiakas runtime/entitlements ei ole yksi niistä eikä sitä koskaan lisätä luetteloon, koska entitlements-lohkonne määrittelee sen jo, ja taustajärjestelmä, joka tuo sen ilman entitlements-lohkoa, ei läpäise samaa tarkistusta. frontend sisältää kentät basePath, mountPath ja framework. nexus sisältää kentät minVersion, maxVersion, capabilities[] ja permissions[].

Jäljellä olevilla lohkoilla on kullakin yksi tehtävä:

Lohko Käyttötarkoitus
settings Asetuksenne jaetussa kehyksessä: groups ja keys, asetettuina kunkin nimeämillä tasoilla
people sweep (service, port): organisaation jäsenet, synkronoituina identiteettipalvelusta, ja käyttöpaikat poistetaan käytöstä, kun joku lähtee
ontology entityTypes ja relationshipTypes: omassa skeemassanne säilytettävä tyypitetty graafi
release groups ja frame: kyvykkyysryhmät, joihin reittinne porrastetaan ja jotka julkaistaan ensin canary-julkaisuna
cells[] Laajennus, joka koostuu useasta käyttöönotettavasta osasta: kullekin name, kind, entrypoint, port, wsPort
pricing model, currency, tiers[] luettelomerkintäänne varten
marketplace category, icon, screenshots, documentation, featured
compliance instruments[], dataResidency, sovereignty
developer, repository, keywords Kuka sen julkaisee ja missä sen koodi sijaitsee
metrics, atlas Kaksi tarkoituksella avointa objektia omia mittarinimiänne ja arkkitehtuuridokumentaation luontia varten

Mitä skeema ei pysty ilmaisemaan

JSON Schema määrää rakenteen; definePlugin lisää säännöt, joita skeema ei pysty ilmaisemaan. Taidon classification ei voi ylittää luottamuskattoa. Vain core- ja verified-laajennukset voivat määritellä tool_using- ja llm_only-taitoja. Jokaisen määritellyn polun on oltava suhteellinen ja samaa alkuperää, ilman URL-protokollaa, ilman //-merkintää ja ilman kenoviivaa, koska URL-jäsennin muuntaa \:n muotoon / ja /\evil.example/x ratkeaa toiseen alkuperään. Jokainen sääntö, jota rekisterin synkronointi soveltaa taitoon, sovelletaan ensin tässä synkronoinnin omalla koodilla, joten validate ja synkronointi nimeävät rikkoutuneen säännön samalla tavalla.

Validointi ja siirtyminen v1-versiosta

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

Virhe tulostaa tarkan polun ja synkronointisäännön kohdalla ensin koodin. Tehkää siitä commit-koukku.

v1-manifesti nostetaan uuteen versioon mekaanisesti. migrate lisää kolme lakilausetta, siirtää kohteen domain kohteeseen domains[] ja kieltäytyy keksimästä aloituspistettä, jota teillä ei ollut. Se validoi tuloksen ennen kuin tulostaa tai kirjoittaa mitään, joten siirto ei koskaan siirrä virhettä työkalusta tietovarastoonne.

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

Lukekaa muutokset ennen kuin teette commitin. Sen lisäämät lakilauseet ovat validoijan kiinnittämä sanamuoto; omaa asennustanne varten asettakaa deploy aiemmin näytettyyn lauseeseen.

Asiakkuuden (tenancy) renderöinti ja roolien provisiointi

Roolioikeuksia tai rivitason suojauksen mallipohjaa ei koskaan kirjoiteta käsin. nexus-tenancy render kirjoittaa ne manifestin kentistä schema ja db:

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

Muodostettu tiedosto luo skeemalle viisi roolia, kukin sen mukaan, mitä sillä ei saa olla: siirtorooli, joka voi vain ryhtyä omistajaksi, omistaja, joka ei voi kirjautua sisään, sovellusrooli pyyntöpolkua varten, raporttirooli, joka näkee vain koosteet, ja kirjanpitorooli, joka voi vain lisätä. Millään roolilla ei ole oikeutta BYPASSRLS. Ainoa tapa sitoa vuokralainen on yksi tietokantafunktio, ja set_config on peruttu kaikilta rooleilta omistajaa lukuun ottamatta.

Sovellettua vuokralaistiedostoa ei koskaan muokata. Muutos on revisio, jolla on oma numeron 0 tiedostonsa, ja organisaatioiden välisten oikeuksien lukupaikka tulee tätä kautta revisiona 2. --graph muodostaa ontology-lohkonne määrittelemän tyypitetyn graafin kaksi taulua seuraavaksi numeroiduksi siirroksenne.

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

Vuokralaistiedosto luo juuri ne roolit, joina suorittaja muodostaa yhteyden, joten tietokannan omistaja soveltaa sen komennolla 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 tietokannan omistajan yhteysmerkkijono, ja <dir> on yksityinen hakemisto. Provisiointi soveltaa perusvuokralaistiedoston ja jokaisen revision järjestyksessä, kirjoittaa tiedostot migrator.url ja app.url (sekä seat.url, kun revisio 2 on olemassa) hakemistoon <dir> tilalla 0600 eikä tulosta mitään salaista. Se asettaa kunkin roolin yhteysrajan arvosta db.maxConnections × db.pods jokaisella ajokerralla. Uusintaajo säilyttää olemassa olevat salasanat, ellette pyydä muuta: --passwords <dir> asettaa ne tiedostoista ja --rotate <roles> antaa nimetyille rooleille uudet. Muuttakaa tiedostot käyttöönottonne salaisuuksiksi.

Sen jälkeen soveltaminen muodostaa yhteyden provisioinnin kirjoittamalla siirtoroolin yhteysmerkkijonolla:

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

Se suorittaa tiedostot 001 alkaen siirtoroolina, jokaisen tiedoston lausekkeen SET ROLE <schema>_owner alaisena, yhden transaktion tiedostoa kohden. Se pitää kirjanpitoa, <schema>.schema_migrations, jossa on kunkin tiedoston tarkistussumma; sovellettu tiedosto, jonka tavut ovat muuttuneet, hylätään nimeltä (CHECKSUM_DRIFT), eikä sitä koskaan ajeta uudelleen tai ohiteta. Jokainen odottava tiedosto jäsennetään todellisella Postgres-kieliopilla ennen ensimmäisen suorittamista, joten hylkäys jättää tietokannan koskemattomaksi. Ainoa otsake, joka tiedostolla voi olla, on -- nexus-migration: transaction=file|per-statement valinnaisine lukitus- ja lausekeaikakatkaisuineen; per-statement on tarkoitettu kohteelle CREATE INDEX CONCURRENTLY.

Portit

nexus-gates suorittaa kaksikymmentäkaksi tarkistusta. Kukin koodaa yhden virheluokan, jotta se ei pääse julkaisuun kahdesti, ja kullakin on itsetesti, joka osoittaa sen epäonnistuvan sen laukaisemiseksi rakennetulla testiaineistolla. Suorittakaa ne ennen pushia:

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test
Tarkistus Mitä se havaitsee
scope-adherence /api-reitti ilman laajuussuojaa; anonyymi polku, joka ei ole täsmälleen määritelty; laitereitti ilman laitesuojaa tai henkilön suojan kanssa
one-fence Vuokralaisehto, joka on määritelty muualla kuin yhdessä paikassa, mukaan lukien käsin tehty käyttöpaikka- tai oikeusrajaus
sql-fence Lauseke, joka lukee tai päivittää rajattua taulua ilman rajausta missä tahansa FROM-, JOIN-, USING- tai UPDATE-kohteessa
migrations-are-scoped Taulu, josta puuttuu akseli, vuokralaisella alkava yhdistelmäavain, vuokralaisen sisältävä viiteavain tai demosarake
migrations-commit-what-they-open Siirto, jonka BEGIN-määrä ei vastaa sen COMMIT- ja ROLLBACK-määrää
no-direct-compute Suora kutsu mallintarjoajalle, moottorille, jonolle tai työnkulkupalvelimelle; välitys-URL:n toinen lukija
no-credentials Mallintarjoajan tunnistetieto, joka on luettavissa tietovarastossa tai ympäristössä
crud-adherence Muuttava reitti, jonka oikeustarkistus ei nimeä mitään rekisterissä olevaa
blocked-backends Reitti, jota ei palvella, estetä nimeltä, hylätä lain perusteella eikä omisteta muualla
every-test-runs Testit, joihin testiskriptin glob-kuvio ei koskaan ulotu
tiles-are-invariant Vuokralaisesta riippumaton välimuistitettu rajapinta, joka lukee vuokralaisarvon tai ohittaa todennuksen
api-contract Rekisteröity reitti, jota manifesti ei määrittele, tai määritelty reitti, jota koodi ei koskaan rekisteröi
rls-present Taulu ilman pakotettua rivitason suojausta; SECURITY DEFINER-funktio ilman kiinnitettyä search_path-asetusta
no-set-config Laajennuskoodi, joka sitoo vuokralaisasetuksen itse
db-role-honest Pyyntöpolku, joka muodostaa yhteyden omistajana tai siirtoroolina tai pyytää oikeutta SUPERUSER tai BYPASSRLS
platform-clients SDK-asiakas, joka on tuotu mutta ei luetteloitu kohteessa backend.platformClients, tai luetteloitu mutta ei koskaan tuotu
rights-register Laajuusreitti ilman määriteltyä oikeutta; oikeustarkistus rekisterin ohella
refusal-ledger Määritelty hylkäystaulu ilman asennettua kirjanpitoa tai hylkäysrunko, joka lähetetään sen ohi
grants-declared Oikeutettu taulu, jota manifesti ei määrittele; käsin jaetut lukupaikan oikeudet
people-declared people-lohko ilman sen siivousreittiä, suojaa ja tauluja
functions-closure Azure Functions -laajennus, jonka palvellut ja määritellyt reitit eivät vastaa toisiaan
declared-input Käsittelijän kyselyparametriluettelo, joka ei vastaa reitin määriteltyä kohdetta query

Hakemisto gates/ sisältää viisi poikkeustiedostoa, joita tarkistus voi lukea (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json ja invariant-seams.json), yksi perustelu merkintää kohden. Tyhjä perustelu lasketaan puuttuvaksi merkinnäksi, ja merkintä, joka nimeää jotain, mitä ei enää ole olemassa, aiheuttaa tarkistuksen epäonnistumisen. Voitte myös lisätä sinne omia tarkistusmoduulejanne, ja nexus-gates ottaa ne käyttöön sisäänrakennettujen rinnalla.

Yhteensopivuus
Yhteensopivuus
Yhteensopivuus näyttää, mikä SDK-versio toimii minkäkin alustaversion kanssa, pika-aloitusoppaan öisten ajojen perusteella. Testaamaton yhdistelmä ilmoittaa sen, ja epäonnistuva yhdistelmä nimeää muutoksen, joka rikkoi sen.

Mallipohjan putki

Mallipohjan mukana ei toimiteta käsin kirjoitettua työnkulkua. Sen putkikonfiguraatio nimeää Dockerfilen, ainoan koontiargumentin (rekisteritunnisteen), siirron kuivaharjoituksen ja käynnistystarkistuksen sekä yhdistämisjonon suorittaman tarkistuksen. Järjestys on se järjestys, jossa haluaisitte epäonnistua.

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

Levykuvalle ajetaan vielä kaksi tarkistusta. Migraation kuiva-ajo ajaa jokaisen tiedoston kertakäyttöiseen Postgres-tietokantaan ennen kuin levykuva voidaan julkaista, käyttäen samaa ajuria kuin tuotantoympäristö: nexus-migrate provision kerran pääkäyttäjänä ja sen jälkeen jokaisen numeroidun tiedoston migraattorina. Käynnistysluotaus käynnistää rakennetun levykuvan sen omalla käynnistyspisteellä ja jokaisella muuttujalla, jonka required-env tulostaa, osoitettuna sijaispalveluihin, jotka hyväksyvät yhteydet mutta eivät koskaan vastaa. Palvelin odottaa tietokantaa rajatun aikaikkunansa puitteissa, ja tämä odotus on läpäisysignaali; määritysten lataaja, joka kieltäytyy käynnistymästä, kaataa käännöksen tässä vaiheessa eikä vasta tuotannossa.

Rakentaminen Communityssa
Rakentaminen Communityssa
Community-versiossa kehittäjä saa samat kultaiset polut, kehitystilan ja datahaarat yhdellä palvelimella, koodin sijaitessa omassa Git-palvelussa. Staging-ympäristö, pilottiyksiköt ja maskatut kopiot tuotantodatasta sisältyvät Enterprise-versioon.

Mitä se maksaa

SDK tekee päätöksiä puolestanne, ja osan niistä olisitte tehneet toisin. Manifesti hylkää avaimet, joita se ei tunnista, reititystaulun on vastattava koodianne täsmälleen, tietokantaroolit eivät ole teidän suunniteltavissanne, ja tarkistusportit kaatavat käännöksen, jos lukuoikeudesta puuttuu valtuutus. Ensimmäisen lisäosani kohdalla käytin kokonaisen päivän väitellen api-contract-komennon kanssa reitistä, jonka olin rekisteröinyt mutta unohtanut määrittää. Se oli oikeassa; reitti oli suojaamaton. Varautukaa siihen, että ensimmäinen lisäosa tuntuu hitaalta, ja siihen, että toinen vie vain kolmanneksen ajasta.