Versio 1.0.0-alpha.1uusin
Luku 2.22
Lisäosan ajoaika (runtime)
SDK-ohjelmistokehityspaketin moduulit, joiden päällä lisäosasi toimii, aina vaikutusalueen vartijasta (scope guard) ja tietokanta-aidasta UNO-välitykseen, tekoälyreitin (AI) lukuun ja lisenssitarkistuksiin. Sen jälkeen testaus oikeaa tietokantaa vasten, taitojen rekisteröinti ja käyttöönotto.
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

SDK:n (ohjelmistokehityspaketti) ajonaikainen puolisko on joukko moduuleja polun @adverant-nexus/plugin-sdk/runtime/* alla sekä testiapuvälineitä polun testing/* alla. Te tuotte ne käyttöönne; ette toteuta niitä uudelleen. Siinä on koko ajatus, ja tarvitsin yhden hylätyn katselmoinnin ottaakseni sen vakavasti: katselmoijan huomautus ensimmäisen lisäosani käsin kirjoitetusta rajaustarkistuksesta oli yksi rivi: "SDK:ssa on tämä jo, ja sinun versiosi hyväksyy MFA-haastetunnisteen (monivaiheinen todennus) istunnoksi".
Tämä luku seuraa pyyntöä käynnissä olevan lisäosan läpi siten kuin täyden palvelun malli sen kytkee: rajausvahti, tietokanta-aita, ainoa sallittu rajanylitys, lähetys UNO:n kautta, tekoälyreitin luku ja lisenssitarkistukset. Sen jälkeen käsitellään testaus, manifestin taitojen rekisteröinti ja käyttöönoton vaiheet.
Vaikutusalue: yksi vartija sovelluskehystä kohden
Jokaisella /api-reitillä on rajausvahti. Se varmentaa bearer-tunnisteen, selvittää siitä kolme akselia (vuokralainen, omistaja, yksikkö), hylkää pyynnön rungon, joka nimeää vuokralaisen, soveltaa reitin oikeutta manifestin rekisteristä ja vasta sitten antaa käsittelijän suorittua. SDK tarjoaa yhden sovittimen kehystä kohden, kaikki moduulista @adverant-nexus/plugin-sdk/runtime/scope ja kaikki samoilla asetuksilla.
| Kehys | Sovitin |
|---|---|
| Express | scopeMiddleware |
| Fastify | requireScope preHandler-funktiona |
| Next | withScope, joka käärii käsittelijän; Next-käsittelijälle ei kerrota sen reittiä, joten withScope ottaa sen kolmantena argumenttina |
Tässä on mallin Express-kytkentä lyhennettynä. Varmentaja on SDK:n oma, ja se pitää tunnisteen identiteettipalvelun istuntomuodon mukaisena: vain HS256; iss, exp, iat ja jti pakollisia; elinikä enintään tunti; eikä MFA-haastetta, toisena käyttäjänä esiintymistä tai OAuth-resurssitunnistetta (delegoidun valtuutuksen avoin standardi) hyväksytä istunnoksi.
import { platformAccessTokenVerifier } from "@adverant-nexus/plugin-sdk/runtime/platform-token";
import { scopeMiddleware } from "@adverant-nexus/plugin-sdk/runtime/scope";
const requireScope = scopeMiddleware({
verify: platformAccessTokenVerifier(config.PLATFORM_JWT_SECRET),
rights: { manifest },
});
router.get("/api/projects", requireScope, async (req, res) => {
res.json({ projects: await db.listProjects(scopeOf(req)) });
});Oikeusvahti soveltaa reitin oikeutta neljässä vaiheessa. Rooli oikeuden never-luettelossa hylkää vastauksella AUTHORITY_EXCEEDED ja barred-sanoilla, eikä mikään käyttöpaikka kumoa sitä. Rooli luettelossa roles hyväksyy, ja lisäksi tarvitaan voimassa oleva käyttöpaikka, kun oikeudessa lukee seat: true. Muussa tapauksessa hyväksyy voimassa oleva käyttöpaikka, joka sisältää oikeuden. Muussa tapauksessa pyyntö hylätään vastauksella AUTHORITY_EXCEEDED, ja siinä nimetään henkilöt, jotka voisivat myöntää käyttöpaikan. Kun annatte vahdille tallennuksen (rights: { manifest, store: { pool, schema } }), se lukee käyttöpaikat kutsujan omalla rajauksella; oikeus, joka nimeää licence-arvon, tarvitsee lisäksi lisenssinlukijan, jota käsitellään alempana.
Käsittelijän sisällä scopeOf(req) on ainoa tapa lukea selvitetty rajaus, ja se heittää virheen, jos vahti ei ole suorittunut. Etuliitteeseen rekisteröity vahti, joka suoritetaan ennen kuin mikään reitti on täsmännyt, vastaa 500 MIDDLEWARE_ORDERING_ERROR; koodinne rekisteröimä reitti, jota manifesti ei määrittele, vastaa 500 UNHANDLED_ERROR. Molemmat epäonnistuvat suljetusti.
Mallin /internal-reitit, joita alusta kutsuu, käyttävät toista järjestelmää. Palveluvahti tarkistaa X-Service-Key:n vakioajassa ja ottaa vuokralaisen alustan X-Organization-ID-arvosta hylkäten MISSING_SERVICE_KEY, INVALID_SERVICE_KEY tai MISSING_ORG_ID_HEADER. Alustan allekirjoitettua kutsukohtaista tunnistetta varten SDK:ssa on requireService (Fastify) ja serviceMiddleware (Express), jotka tarkistavat myös, mille taidolle ja reitille tunniste on luotu, ja hylkäävät kahdesti käytetyn tunnisteen.
Tietokanta-aita: tenantFence ja withScopedTx
Jokainen rajattuun tauluun kohdistuva lause muodostaa aidan ja suoritetaan rajatun transaktion sisällä:
import { withScopedTx } from "@adverant-nexus/plugin-sdk/runtime/db";
import { tenantFence } from "@adverant-nexus/plugin-sdk/runtime/fence";
async function listProjects(scope: ResolvedScope) {
// Projects are owner-private inside the organisation, so the owner axis is passed explicitly.
const f = tenantFence(scope, { alias: "p", owner: scope.owner });
const r = await withScopedTx(pool, scope, { schema: SCHEMA }, (db) =>
db.query(`SELECT p.* FROM anomaly_review.reviews p WHERE ${f.where} ORDER BY p.created_at DESC`, f.params),
);
return r.rows;
}tenantFence(scope, options) rakentaa predikaatin ja sen parametrit selvitetystä rajauksesta. Antakaa owner henkilökohtaisille tauluille; jättäkää se pois organisaation artefakteista, joissa omistaja kertoo alkuperän. Kun lauseella on jo parametreja, startIndex kertoo aidalle, mistä numerointi alkaa. Lisäys ei koskaan ota akseleita syötteenä: se kirjoittaa scope.tenant, scope.owner ja scope.unit rajauksesta.
withScopedTx sitoo kaikki kolme akselia yhtä transaktiota varten skeeman ainoan sidontafunktion kautta ja suorittaa sitten takaisinkutsunne. Toinen sidonta samassa transaktiossa aiheuttaa virheen SCOPE_ALREADY_BOUND (500: koodinne sitoi kahdesti; kutsuja ei tehnyt mitään väärin). Puuttuva tai nolla-arvoinen vuokralainen tai omistaja aiheuttaa virheen SCOPE_PREDICATE_INVALID (403). Asetus on transaktiokohtainen, joten yhteysvarannon yhteys ei voi kuljettaa yhtä vuokralaista seuraavaan pyyntöön.
Kaksi rinnakkaista funktiota kattaa tapaukset, jotka eivät ole henkilön pyyntöjä. withTenantScopedTx sitoo vuokralaisen ja yksikön ilman omistajaa riveille, joita kone lukee (laiterekisteri), ja hylkää rajauksen, jossa on omistaja. maintenanceScope(reason) vaatii organisaation laajuista toimintoa ilmoittamaan ääneen, mikä se on, ennen kuin omistajan transaktio avautuu. Koodiaita ja pakotettu rivitason suojaus ovat kaksi mekanismia samalle säännölle; käynnistystarkistus kieltäytyy kuuntelemasta, kunnes tietokanta osoittaa jälkimmäisen olevan voimassa (muuten DB_ROLE_BYPASSES_ISOLATION).
Jokainen hylkäys on rivi
Malli asentaa vielä yhden väliohjelmiston, kerran, rungon jäsentimen ja reitittimien väliin: hylkäyskirjanpidon.
import { recordRefusals } from "@adverant-nexus/plugin-sdk/runtime/refusal-ledger";
app.use(express.json({ limit: "256kb" }));
app.use(recordRefusals({ pool, schema: SCHEMA }));Se käärii vastauksen niin, että jokainen henkilön lukema hylkäys, tuli se oikeusvahdilta, käsittelijältä tai tallennukselta, kirjoitetaan skeemanne refusal-tauluun kyseisen henkilön oman rajatun transaktion sisällä ennen rungon lähettämistä. Anonyymi 401 ei kirjoita mitään. Jos riviä ei voida kirjoittaa, vastaukseksi tulee UNHANDLED_ERROR: "ei"-vastausta, jota tuote ei voi tallentaa, ei lähetetä ikään kuin se olisi tallennettu. Käynnistys suorittaa assertRefusalLedger:n tarkistaakseen, että taulu voi ottaa vastaan kirjanpidon rivin, ja tallennus voi kutsua noteSubject({ recordId, isDemo }):ää, jotta jokainen hylkäys nimeää tietueen, jota se koski. Kun asiakas kysyy, miksi joku käännytettiin pois viime tiistaina, vastaus on kysely, ei arvaus.
Ainoa ylitys: kirjattu vain luku -valtuutus
Kun yksi asiakkaistanne tekee työtä toiselle ja toinen saa tarkastaa sen, rajan yli on yksi hyväksytty tie. Rivit omistava organisaatio kirjaa myönnöksen. Lukijan organisaatio päästää henkilön sisään käyttöpaikalla, joka sisältää oikeuden granted.read, jonka on nimettävä owner ja admin kohdassa never. Luku suoritetaan kuudentena tietokantaroolina, lukupaikkana, joka voi valita vain databases[].granted:n luettelemista tauluista:
const r = await withSeatTx({ app: appPool, seat: seatPool }, seatsOf(req), { holder, grantId }, { schema: "anomaly_review" }, (db) => {
const f = grantFence(db.seat, { alias: "r" });
return db.query(`SELECT r.review_id FROM anomaly_review.reviews r WHERE ${f.where}`, f.params);
});
if (!r.ok) return res.status(r.status).json(r.refusal);withSeatTx kirjoittaa ensin katselumerkinnän lukijan omaan vuokralaiseen ja sitoo sitten lukupaikan myönnökseen, mikä kirjoittaa katselumerkinnän haltijan vuokralaiseen. Tietokannan oma käytäntö tarkistaa, että myönnös nimeää lukijan organisaation, kattaa taulun, on alkanut, ei ole päättynyt eikä sitä ole peruttu ja että tämä transaktio kirjoitti katselumerkintänsä. Luku, joka ohittaa katselumerkinnän, ei näe mitään. Käynnistyksessä assertSeatAtBoot(seatPool, schema) tarkistaa, että seat.url:sta avattu yhteysvaranto todella on lukupaikka eikä mitään muuta, ja hylkää muuten virheellä DB_SEAT_ROLE_INVALID.
Välitys UNOn kautta
Kaikki laskenta kulkee yhden asiakasohjelman kautta, joka rakennetaan yhdessä tiedostossa suljetulla sallittujen luettelolla:
import { UnoClient } from "@adverant-nexus/plugin-sdk/runtime/uno";
/** The namespaced job types this surface may dispatch. Closed; edit in code. */
export const DISPATCHABLE = Object.freeze([`${manifest.name}.sentiment_score`] as const);
export function createUno(deps: UnoDeps): UnoClient {
return new UnoClient({
baseUrl: deps.dispatchUrl,
serviceKey: deps.serviceKey,
callerService: manifest.name,
dispatchable: DISPATCHABLE,
});
}Sallittujen luettelo on tarkoituksella moduulitason vakio. Jos operaattori voisi laajentaa sitä määrityksistä, reitistä tulisi lähetysvälityspalvelin koko rekisterille. Mallin oma testi varmistaa, että luettelo nimeää täsmälleen ne työtyypit, joiksi manifesti käännetään.
Kuori
Lähetyksen pakollisessa ytimessä on kuusi kenttää. Asiakasohjelma täyttää vuokralaisen ja toimijan varmennetusta rajauksesta, ei koskaan pyynnöstä:
| Kenttä | Mitä se sisältää |
|---|---|
jobType |
Nimiavaruudellinen työtyyppi, <plugin name>.<skill id> |
organizationId |
Vuokralainen, rajauksesta |
userId |
Toimija, rajauksesta, auditointia ja laskutusta varten |
inputParams |
Taidon syöte. Se ei koskaan sisällä vuokralaisen tunnusta; syöte, joka sisältää sen, hylätään lähetyksessä |
priority |
critical, high, normal tai low |
pluginId |
Manifestinne name. Jokainen lähetys ilmoittaa, mistä lisäosasta se on peräisin |
Valinnaisia kenttiä ovat correlationId (UUID (yleisesti yksilöllinen tunniste), tai luodaan uusi) ja callbackUrl, jota plugin_queue-taito tarvitsee, jotta työntekijä tietää, minne tulos lähetetään.
const accepted = await uno.dispatch(scope, {
jobType: DISPATCHABLE[0],
inputParams: { text: text.body },
priority: "normal",
pluginId: manifest.name,
correlationId: crypto.randomUUID(),
});
if (!accepted.ok) return res.status(statusFor(accepted.refusal.code)).json(accepted.refusal);
res.status(202).json(accepted.value);202, sitten kysely
Jokainen lähetys asetetaan jonoon. Vastaus on aina 202 tunnisteineen (jobId, runId, traceId, status), ei koskaan tulos. Tulos saadaan kyselemällä työn tilaa tai takaisinkutsustanne. uno.peek(jobId, { scope }) lukee sen kerran ja awaitJob kyselee, kunnes tila on lopullinen; molemmat lähettävät vuokralaisen varmennetusta rajauksesta, ja molemmat tarkistavat palautetun rivin organization_id-arvon kutsujan vuokralaista vasten omalla puolellanne verkkokutsua ja hylkäävät poikkeaman virheellä SCOPE_REFUSED.
Lukekaa ajorivi sen omalla kirjoitusasulla. Lähetysvastauksessa lukee jobId; rivissä lukee job_id, organization_id ja plugin_id. Tulos- ja virhesarakkeet ovat result, error, error_code ja error_troubleshooting. completed ja failed ovat lopullisia. timed_out, cancelled ja system_failure tulevat siivoajalta, ja myöhästynyt tulos voi vielä korjata ne. Asiakasohjelma, joka pitää mitä tahansa näistä jäsentämättömänä, hylkää rivejä, joita alusta kirjoittaa joka päivä.
Hyväksyntäpidätys
Manifestin taito, joka ilmoittaa approval, pidätetään lähetyksessä. Tällöin 202:ssa lukee status: "awaiting_approval", ja se sisältää waitpointId:n manifestin antamine perusteluineen. Ajo pysyy pidätettynä, kunnes nimetty henkilö tekee siitä päätöksen. uno.approve ja uno.resolveWaitpoint lähettävät vuokralaisen ja kutsujan toimijana, ja muun kuin varmennetun kutsujan tekemä päätös hylätään. Hyväksyntä vapauttaa työn kerran ja suorittaa lähetystarkistukset uudelleen; hylkäys päättää sen tilaan failed. Toinen päätös hylätään, samoin päätös pidätyksen vanhennuttua. Jos tuotteenne edellyttää, että hyväksyjä on eri henkilö kuin ehdottaja, valvokaa sitä päätöksen tekevällä reitillä: alusta kirjaa molemmat.
Näyttäkää pidätetty työ pidätettynä. Älkää kertoko henkilölle, että hänen napsautuksensa vapautti sen, ennen kuin ajorivi sanoo niin.
Tekoäly: toiveet taitorivillä ja yksi luku
Lisäosanne ei koskaan kutsu mallia. Kun manifestin taito tarvitsee sellaista (llm_only tai tool_using, luottamustasolla core tai verified), ilmaisette toiveet sen rekisteririvillä, ja reititin päättää organisaation omasta valikoimasta:
{
"execution_config_skill": {
"preferredProvider": "gemini",
"capabilityProfile": { "needsToolUse": true, "dataResidency": "eu_only" }
}
}preferredProvider ja preferredModel ovat toiveita, joita reititin noudattaa vain, kun organisaatiolla on kyseinen palveluntarjoaja käytössä ja tunnistetiedoilla varustettuna. capabilityProfile suodattaa eikä koskaan valitse; sen dataResidency (eu_only, us_only tai any) on ehdoton rajoite, jonka reititin täyttää tai hylkää. Kaikkien jättäminen pois on yleensä oikein. modelOverride on olemassa harvinaista taitoa varten, joka tarvitsee yhden tarkan mallin, ja se tekee rinnalla olevat toiveet vaikutuksettomiksi; välttäisin sitä, ellei taito ole merkityksetön millä tahansa muulla mallilla.
Kun käyttöliittymänne on näytettävä, mitä mallia reititin käyttäisi, lukekaa se, älkää ennustako sitä:
import { createAIRouteClient } from "@adverant-nexus/plugin-sdk/runtime/ai-route";createAIRouteClient(...).effectiveRoute() on AI Provider Routerin ainoa hyväksytty lukutapa. Se ottaa yhdyskäytävän osoitteen, kutsujan oman bearer-tunnisteen ja alustanne tunnisteen eikä lähetä tekoälypyyntöä. Se palauttaa palveluntarjoajan ja mallin, käytännön sallimat palveluntarjoajat sekä sen, toimiiko valittu päätepiste local- vai external-tilassa. Kun reitti ei ole käytettävissä, se palauttaa reitittimen hylkäyksen sanallisesti (NO_PROVIDER_FOR_ROLE, MODEL_CAPABILITY_UNAVAILABLE tai NO_MODEL_FOR_ROLE_AND_PROVIDER korjausohjeineen), ei koskaan oletusmallia. Näyttäkää tämä hylkäys henkilölle; se on hänen organisaationsa määritys, joka puhuu.
Lisenssitarkistukset
Kolme mekanismia tarkistaa lisensoinnin kolmella tarkkuustasolla.
Oikeus, joka nimeää lisenssin. Yksinkertaisin. Manifestissa oikeudella on licence: "<feature>", ja vahti kysyy identiteettipalvelulta kutsujan omalla tunnisteella, sisältääkö organisaation lisenssi sen, ennen kuin yhtään roolia luetaan. Rakentakaa vahti lukijan kanssa:
import { createLicenceReader } from "@adverant-nexus/plugin-sdk/runtime/licence";
const requireScope = scopeMiddleware({
verify,
rights: { manifest, store: { pool, schema: SCHEMA }, licence: createLicenceReader({ baseUrl: config.NEXUS_AUTH_URL }) },
});Lisenssi, joka ei sisällä ominaisuutta, hylkää kaikki virheellä LICENCE_LOCKED nimeten, mikä sen sisältää, ja kertoen, että organisaation omistajat ja ylläpitäjät voivat ottaa sen käyttöön. Lisenssi, jota ei voida lukea, hylkää virheellä UNHANDLED_ERROR: lukittua ominaisuutta ei koskaan tarjota sen vuoksi, ettei lisenssiä tavoitettu. Vastaukset muistetaan 30 sekunnin ajan organisaatio- ja ominaisuuskohtaisesti.
Tuoteportti. createProductGate({ baseUrl, product }) moduulista runtime/product-gate kysyy käyttöoikeustarkistukselta, onko kutsujan organisaatiolla tuotteenne ylipäätään, ja sen middleware() suoritetaan rajausvahdin jälkeen. Kielteinen tulos on ENTITLEMENT_DENIED; tarkistus, jota ei tavoiteta, on ENTITLEMENT_UNREACHABLE, eikä portti koskaan käsittele toista toisena.
Itse lisenssiasiakirja. Koodi, jonka on päätettävä itse allekirjoitetun lisenssin perusteella, kuten toimialapaketin suljettu moduuli, käyttää funktiota verifyLicenceDocument(docText, opts) moduulista runtime/licence-document. Se on puhdas funktio: ei verkkokutsua, ei ympäristömuuttujaa, ei tiedostoa. Se tarkistaa molemmat allekirjoitukset koontiversion mukana tulevia luottamusjuuria vasten ja palauttaa tilan (VALID, WARN, GRACE, RESTRICT, TERMINATE tai ABSENT) myönnösten, lisäosien ja toimialapakettien kanssa. licenceAllows(verdict, featureGroup, action, tenantId?) kertoo sitten, saatteko use vai provision ryhmän alla. RESTRICT sallii use ja vastaa provision arvolla LICENCE_LOCKED, joten käynnissä oleva työ jatkuu eikä mitään uutta aloiteta.
Testaus
Mallin testit näyttävät kaavan; nämä ovat sen taustalla olevat työkalut.
Rajausjäljitelmät. Rakentakaa selvitetyn rajauksen jäljitelmä kerran tiedostossa test/scope-fakes.ts ja injektoikaa se kaikkialle, myös puuttuvat tapaukset: ei yksikköä, ei tunnistetta, tunniste nolla-arvoisella organisaatiolla. Hylkäyspolut ovat tuote.
Jäljitelty lähetyskuljetus. UnoClient ottaa fetch, now ja sleep, joten yksikkötesti ei koskaan koske verkkoon. Varmistakaa kuoren kentät, 202-muoto, kysely lopulliseen riviin sen organization_id-arvon kanssa sekä se, että toisen vuokralaisen rivi hylätään.
Aito Postgres. Valekyselyfunktio todistaa SQL-merkkijonon. Se ei voi todistaa, että pakotettu rivitason suojaus pitää tai että tiedostot ajetaan järjestyksessä migraattorina. testing/ephemeral-postgres käynnistää kertakäyttöisen palvelimen ja ajaa samat nexus-migrate, jotka tuotanto ajaa:
import { EPHEMERAL_REMEDY, migrated, startEphemeralPostgres } from "@adverant-nexus/plugin-sdk/testing/ephemeral-postgres";
const pg = await startEphemeralPostgres(); // null off CI: skip each case by name with EPHEMERAL_REMEDY
const db = migrated(pg!, "plugin_test", { root }); // provision as the superuser, then every file as the migrator
// connect as db.appUrl and run the boot checks the server runsCI:n (jatkuva integraatio) ulkopuolella koneella, jolla ei ole Postgres-palvelinta, jokainen tietokantatapaus ohitetaan nimeltä korjausohjeen kera, eikä tulos ole koskaan vihreä. CI:ssä sama puute kaataa testisarjan (EPHEMERAL_POSTGRES_UNAVAILABLE_IN_CI), koska ohitettu rivitason suojauksen testi on vihreä portti, joka ei mitannut mitään. Palvelimen käynnistymistä odotetaan enintään 180 sekuntia, ja vahtiprosessi pysäyttää sen, kun testiprosessi päättyy.
Eristystestikehys. testing/isolation-harness-paketin runIsolationHarness(target) lukee jokaisen sovelluksesi liittämän reitin ja hyökkää kuhunkin toisen organisaation ylläpitäjänä ja kollegana. Sitten se hyökkää uudelleen niin, että koodiaita on poistettu, tietokanta-aita on poistettu ja molemmat on poistettu. Reitti on PROVEN vain, kun hyökkäys epäonnistuu kumman tahansa aidan ollessa paikallaan ja ulottuu uhrin tietoihin molempien ollessa poistettuina, joten tiedätte, että testi ylipäätään pystyy havaitsemaan vuodon. Se lähettää kunkin reitin ilmoitetun kyselyn ja esimerkkirungon, joten myös tyhjän pyynnön hylkäävä reitti tavoitetaan. Kiinnittäkää ledgerOf(report) testiin ja epäonnistukaa tuloksella defectsOf(report).
Rekisteröinti: manifestista taitorekisteriin
Manifestinne taidot päätyvät taitorekisteriin yhtä polkua pitkin:
manifest.skills[] → compileRegistry(manifest) → POST /api/v1/plugins/sync
compileRegistry muuntaa validoidun manifestin nexus.plugin-sync/v1-rungoksi. Malli tekee sen tuonnin yhteydessä, joten virheellinen manifesti kaataa käännöksen:
import { compileRegistry, definePlugin } from "@adverant-nexus/plugin-sdk";
export const manifest = definePlugin(raw);
export const registryPayload = compileRegistry(manifest);{
"contract": "nexus.plugin-sync/v1",
"pluginId": "anomaly-review",
"version": "0.3.0",
"skills": [ { "job_type": "anomaly-review.excursion_summary", "tier": "host_callback", "classification": "tenant" } ]
}Synkronointi on deklaratiivinen: lähettäkää koko taitojoukko joka kerta, ja pois jätetty taito poistetaan käytöstä sen historian säilyessä. Se on tiukka: tuntematon kenttä, toisen tason kenttä tai null hylätään, kaikki rikkeet palautetaan yhdessä yhdessä 400 SYNC_CONTRACT_VIOLATION-vastauksessa, eikä mitään kirjoiteta, kun rikkeitä on yksikin. Ja se kirjoittaa yhden rekisteririvin taitoa kohden, avaimena nimiavaruudella varustettu työtyyppi, ja mukana jokainen sarake, jonka välittäjä lukee, joten taito on ajettavissa heti, kun synkronointi vastaa 200.
Laajennus on todennettu kutsuja, ei koskaan rungon kenttä. Kutsukaa synkronointia laajennuksenne omasta työkuormasta mTLS:n (molemminpuolinen TLS: Transport Layer Security, jossa varmenne on molemmissa päissä) kautta. Skills Engine lukee työkuormanne asiakasvarmenteen, jonka SPIFFE-identiteetti (spiffe://<trust-domain>/ns/<namespace>/sa/<service-account>) nimeää nimiavaruuden ja palvelutilin, ja hakee kyseiselle nimiavaruudelle kirjatun laajennuksen ja omistavan organisaation. Rungon pluginId-arvon on täsmättävä; se on tarkistus, ei valitsin. Jokainen rivi kirjoitetaan tällä laajennuksella ja organisaatiolla.
| Tila | Koodi | Merkitys |
|---|---|---|
| 200 | {contract, pluginId, version, created, updated, unchanged, disabled, skills} |
|
| 400 | SYNC_CONTRACT_VIOLATION |
Jokainen rike lueteltuna kohteessa violations[]; mitään ei kirjoitettu |
| 401 | UNAUTHORIZED |
Virheellinen tai puuttuva palveluavain |
| 401 | CALLER_IDENTITY_UNVERIFIED |
Ei luettavaa asiakasidentiteettiä |
| 403 | DELIVERY_IDENTITY_MISSING |
Kutsuva nimiavaruus ei kuulu millekään laajennukselle |
| 403 | PLUGIN_ID_MISMATCH |
Runko nimeää toisen laajennuksen |
| 409 | REGISTRY_CONFLICT |
Työtyypin omistaa joku muu tai se rekisteröitiin synkronoinnin ulkopuolella; mitään ei kirjoitettu |
Antakaa käyttöönottovaiheen epäonnistua millä tahansa muulla tilakoodilla kuin 200. Mikään muu tila ei tarkoita, että taitonne on rekisteröity.
Käyttöönotto
Perehdytys suoritetaan kymmenenä järjestettynä vaiheena, joista kunkin voi ajaa uudelleen, peruuttaa tai palauttaa erikseen:
- Kloonaa tietovarasto ja validoi se.
- Jäsennä manifesti.
- Tarkista se tietoturvaongelmien varalta.
- Rakenna image.
- Työnnä se asennuksen rekisteriin.
- Määritä sen verkkotunnukset.
- Ota se käyttöön asennuksen julkaisukanavien kautta.
- Odota kuntotarkistusta.
- Rekisteröi laajennus.
- Ilmoita kehittäjälle.
Ennen käyttöönottoa manifestia ja rakennettua imagea vastaan ajetaan viisi yhdenmukaisuustarkistusta: manifesti jäsentyy ja sisältää pakolliset kenttänsä; jokainen ilmoitettu reitti on todellinen rekisteröity reitti; laajennus omistaa skeemansa eikä kirjoita mitään sen ulkopuolelle; resurssipyynnöt on ilmoitettu ja ne ovat rajoissa; ja imagessa on toimiva kuntokäsittelijä. Käynnistyksen yhteydessä itsensä rekisteröivä laajennus ajaa saman sopimuksen omalla valtuudellaan, joten tarkistuksista tulee sen CI eikä putken. Yhden ohittaminen ei lyhennä perehdytystä; se siirtää virheen ajonaikaiseksi.
Manifestinne brändäys tarjoillaan ilman todennusta verkkotunnuksen perusteella, koska kirjautumissivu tarvitsee sitä ennen kuin kenelläkään on tunnistetietoja. Käsitelkää kaikkea kohteessa branding julkisena.
GATE_CANNOT_BE_SKIPPED.Mitä ajoaika ei tee puolestasi
Ajoympäristö pitää huolen eristyksestä, välityksestä ja mallien käytöstä. Se ei tee tuotelogiikastanne oikeaa, eikä se tee hitaasta kyselystä nopeaa: jokainen lause ajetaan sidotun transaktion sisällä manifestinne db-lohkon ilmoittamin aikakatkaisuin, ja lause, joka ylittää statementTimeoutMs, peruutetaan eikä sitä odoteta. Mitoittakaa kyselynne sen mukaan. Lisäksi hyväksyntäpito, lukupaikka ja lisenssinlukija lisäävät kukin edestakaisen kutsun tai transaktion. Poikkeamien tarkastelun laajennuksessani lisenssitarkistus lisäsi muutaman millisekunnin pyyntöä kohden, kunnes sen 30 sekunnin muisti lämpeni, mikä oli kohtuullinen hinta siitä, ettei lukittua ominaisuutta koskaan tarjoiltu.

