Verzió 1.0.0-alpha.1legújabb
2.22. fejezet
A beépülő modul futtatókörnyezete
Az SDK (szoftverfejlesztő készlet) moduljai, amelyeken a beépülő modulja fut, a hatókörvédőtől (scope guard) és az adatbázis-kerítéstől (database fence) az UNO diszpécserig, az AI (mesterséges intelligencia) útvonal-kiolvasásig és a licencellenőrzésekig. Ezt követi a valós adatbázison végzett tesztelés, a képességek regisztrálása és a bevezetés (onboarding).
Ezt az oldalt AI fordította az eredeti angol szövegből. Ha bármi nem egyértelmű, az angol nyelvű oldal az irányadó. Oldal olvasása angolul

Az SDK (szoftverfejlesztői készlet) futásidejű fele a @adverant-nexus/plugin-sdk/runtime/* alatti modulok összessége, valamint a testing/* alatti tesztsegédeszközök. Ezeket Ön importálja, nem implementálja újra. Ez a lényeg, és nekem egy elutasított felülvizsgálatba került, mire komolyan vettem: a bíráló megjegyzése az első pluginom kézzel írt hatókör-ellenőrzésére egyetlen sor volt: „ez már megvan az SDK-ban, és a tiéd munkamenetként fogad el egy MFA (többtényezős hitelesítés) kihívástokent”.
Ez a fejezet egy kérést követ végig egy futó pluginon, úgy, ahogyan a teljes szolgáltatásos sablon összekapcsolja: a hatókörőr, az adatbázis-kerítés, az egyetlen engedélyezett átlépés, a kiküldés az UNO-n keresztül, az AI (mesterséges intelligencia) útvonal lekérdezése és a licencellenőrzések. Ezután a tesztelést, a manifeszt képességeinek regisztrálását és a bevezetési lépéseket tárgyalja.
Hatókör: keretrendszerenként egy védőelem (guard)
Minden /api útvonalon ott van a hatókörőr. Ellenőrzi a bearer tokent, feloldja belőle a három tengelyt (bérlő, tulajdonos, egység), elutasítja a bérlőt megnevező kéréstörzset, alkalmazza az útvonal jogosultságát a manifeszt nyilvántartásából, és csak ezután engedi futni a kezelőt. Az SDK keretrendszerenként egy adaptert biztosít, mindet a @adverant-nexus/plugin-sdk/runtime/scope csomagból, és mind ugyanazokat a beállításokat fogadja.
| Keretrendszer | Adapter |
|---|---|
| Express | scopeMiddleware |
| Fastify | requireScope, preHandlerként |
| Next | withScope, amely becsomagolja a kezelőt; egy Next-kezelő nem kapja meg az útvonalát, ezért a withScope harmadik argumentumként veszi át |
Íme a sablon Express-összekapcsolása, rövidítve. Az ellenőrző az SDK-é, és a tokent az identitásszolgáltatás munkamenet-formátumához köti: csak HS256; kötelező a iss, a exp, a iat és a jti; legfeljebb egyórás élettartam; és sem MFA-kihívás-, sem megszemélyesítési, sem OAuth- (a delegált engedélyezés nyílt szabványa) erőforrástoken nem fogadható el munkamenetként.
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)) });
});A jogosultságőr négy lépésben alkalmazza egy útvonal jogosultságát. Ha a szerepkör szerepel a jogosultság never listájában, az őr AUTHORITY_EXCEEDED kóddal és a barred szavakkal utasít el, és ezt semmilyen hely nem oldja fel. Ha a szerepkör a roles listában szerepel, az őr beenged, emellett élő hellyel is, ha a jogosultság ezt mondja: seat: true. Egyébként egy, a jogosultságot hordozó élő hely enged be. Egyébként a kérés elutasításra kerül AUTHORITY_EXCEEDED kóddal, megnevezve azokat a személyeket, akik helyet adhatnak. Adjon az őrnek egy tárolót (rights: { manifest, store: { pool, schema } }), és az a hívó saját hatókörében olvassa a helyeket; a licence értéket megnevező jogosultsághoz licencolvasó is szükséges, erről lentebb olvashat.
Egy kezelőn belül a scopeOf(req) az egyetlen módja a feloldott hatókör olvasásának, és kivételt dob, ha az őr nem futott le. Egy előtagra regisztrált őr, amely azelőtt fut, hogy bármely útvonal illeszkedett volna, 500 MIDDLEWARE_ORDERING_ERROR választ ad; a kódja által regisztrált, de a manifesztben nem deklarált útvonal 500 UNHANDLED_ERROR választ ad. Mindkettő zárt állapotban hibázik.
A sablon /internal útvonalai, amelyeket a platform hív, a másik rendszert használják. A szolgáltatásőr állandó időben ellenőrzi a X-Service-Key értéket, és a bérlőt a platform X-Organization-ID értékéből veszi, az elutasítást pedig MISSING_SERVICE_KEY, INVALID_SERVICE_KEY vagy MISSING_ORG_ID_HEADER kóddal jelzi. A platform hívásonkénti aláírt tokenjéhez az SDK a requireService (Fastify) és a serviceMiddleware (Express) elemet biztosítja, amelyek azt is ellenőrzik, mely képességhez és útvonalhoz bocsátották ki a tokent, és elutasítják a kétszer felhasznált tokent.
Az adatbázis-kerítés: tenantFence és withScopedTx
Minden hatókörös táblára vonatkozó utasítás összeállítja a kerítést, és hatókörös tranzakción belül fut:
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;
}A tenantFence(scope, options) egy feloldott hatókörből építi fel a predikátumot és annak paramétereit. Személyes táblák esetén adja át a owner értéket; hagyja el olyan szervezeti elemeknél, ahol a tulajdonos az eredetet jelzi. Ha az utasításnak már vannak paraméterei, a startIndex mondja meg a kerítésnek, honnan kezdje a számozást. Egy beszúrás soha nem fogadja bemenetként a tengelyeket: a scope.tenant, scope.owner és scope.unit értéket a hatókörből írja.
A withScopedTx a séma egyetlen kötőfüggvényén keresztül egy tranzakcióra köti mindhárom tengelyt, majd futtatja a visszahívást. Ugyanabban a tranzakcióban egy második kötés SCOPE_ALREADY_BOUND hibát vált ki (500: a kódja kétszer kötött; a hívó semmit sem rontott el). Hiányzó vagy nulla bérlő vagy tulajdonos SCOPE_PREDICATE_INVALID hibát vált ki (403). A beállítás tranzakció-lokális, így egy készletből származó kapcsolat nem viheti át az egyik bérlőt a következő kérésbe.
Két testvérfüggvény fedi le azokat az eseteket, amelyek nem egy személy kérései. A withTenantScopedTx tulajdonos nélkül köti a bérlőt és az egységet olyan sorokhoz, amelyeket gép olvas (az eszköznyilvántartás), és elutasítja a tulajdonost hordozó hatókört. A maintenanceScope(reason) arra kényszeríti a szervezetszintű műveletet, hogy kimondja, mi is az, mielőtt a tulajdonos tranzakciója megnyílik. A kódkerítés és a kikényszerített sorszintű biztonság két mechanizmus egyetlen szabályhoz; az indítási ellenőrzés addig nem kezd figyelni, amíg az adatbázis nem bizonyítja, hogy a második teljesül (különben DB_ROLE_BYPASSES_ISOLATION).
Minden elutasítás egy új sor
A sablon még egy köztes szoftvert telepít, egyszer, a törzselemző és az útválasztók közé: az elutasítási naplót.
import { recordRefusals } from "@adverant-nexus/plugin-sdk/runtime/refusal-ledger";
app.use(express.json({ limit: "256kb" }));
app.use(recordRefusals({ pool, schema: SCHEMA }));Ez becsomagolja a választ, így minden elutasítás, amelyet egy személy olvas, akár a jogosultságőrtől, egy kezelőtől vagy egy tárolótól származik, a törzs elküldése előtt bekerül a séma refusal táblájába, az adott személy saját hatókörös tranzakcióján belül. Egy névtelen 401 semmit sem ír. Ha a sor nem írható, a válasz UNHANDLED_ERROR lesz: egy „nem”, amelyet a termék nem tud rögzíteni, nem kerül úgy elküldésre, mintha rögzítették volna. Az indítás futtatja a assertRefusalLedger ellenőrzést, hogy a tábla befogadja-e a napló sorát, és egy tároló meghívhatja a noteSubject({ recordId, isDemo }) függvényt, hogy minden elutasítás megnevezze azt a rekordot, amelyre vonatkozott. Amikor egy ügyfél megkérdezi, miért utasítottak el valakit múlt kedden, a válasz egy lekérdezés, nem pedig találgatás.
Az egyetlen átjárás: egy rögzített, csak olvasható engedély
Ha az egyik ügyfele munkát végez egy másiknak, és a másik ellenőrizheti azt, egyetlen jóváhagyott módja van a határ átlépésének. A sorokat birtokló szervezet engedélyt rögzít. Az olvasó szervezete egy olyan helyen keresztül enged be egy személyt, amely a granted.read jogosultságot hordozza, és amelynek a never mezőben meg kell neveznie a owner és a admin értéket. Az olvasás egy hatodik adatbázis-szerepkörként, az olvasási helyként fut, amely csak a databases[].granted által felsorolt táblákból kérdezhet le:
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);A withSeatTx először az olvasó saját bérlőjében írja meg a betekintést, majd az olvasási helyet az engedélyhez köti, ami a birtokos bérlőjében írja meg a betekintést. Az adatbázis saját házirendje ellenőrzi, hogy az engedély megnevezi-e az olvasó szervezetét, lefedi-e a táblát, megkezdődött-e, nem járt-e le, nem vonták-e vissza, és hogy ez a tranzakció megírta-e a betekintését. A betekintést kihagyó olvasás semmit sem lát. Indításkor a assertSeatAtBoot(seatPool, schema) ellenőrzi, hogy a seat.url alapján megnyitott készlet valóban a hely, és semmi több, ellenkező esetben DB_SEAT_ROLE_INVALID hibával utasít el.
Küldés az UNO-n keresztül
Minden számítás egyetlen kliensen keresztül megy, amely egyetlen fájlban készül, zárt engedélyezési listával:
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,
});
}Az engedélyezési lista szándékosan modulszintű konstans. Ha egy üzemeltető konfigurációból bővíthetné, az útvonal az egész nyilvántartás kiküldési proxyjává válna. A sablon saját tesztje ellenőrzi, hogy a lista pontosan azokat a feladattípusokat nevezi meg, amelyekre a manifeszt lefordul.
A boríték
Egy kiküldés kötelező magjában hat mező található. A kliens a bérlőt és a szereplőt az ellenőrzött hatókörből tölti ki, soha nem a kérésből:
| Mező | Mit tartalmaz |
|---|---|
jobType |
A névtérrel ellátott feladattípus, <plugin name>.<skill id> |
organizationId |
A bérlő, a hatókörből |
userId |
A szereplő, a hatókörből, auditáláshoz és számlázáshoz |
inputParams |
A képesség bemenete. Soha nem tartalmaz bérlőazonosítót; az ilyet tartalmazó bemenet a kiküldéskor elutasításra kerül |
priority |
critical, high, normal vagy low |
pluginId |
A manifesztje name értéke. Minden kiküldés deklarálja a kezdeményező pluginját |
A választható mezők közé tartozik a correlationId (egy UUID (univerzálisan egyedi azonosító), vagy egy újonnan generált) és a callbackUrl, amelyre egy plugin_queue képességnek szüksége van, hogy a feldolgozó tudja, hová küldje az eredményét.
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, majd lekérdezés
Minden kiküldés sorba kerül. A válasz mindig 202 azonosítókkal (jobId, runId, traceId, status), soha nem eredmény. Az eredmény a feladat lekérdezéséből vagy az Ön visszahívásából érkezik. A uno.peek(jobId, { scope }) egyszer olvassa be, a awaitJob pedig végállapotig kérdezi le; mindkettő az ellenőrzött hatókörből küldi a bérlőt, és mindkettő a hálózati hívás Ön felőli oldalán veti össze a visszakapott sor organization_id értékét a hívó bérlőjével, eltérés esetén SCOPE_REFUSED hibával utasítva el.
A futási sort a saját írásmódjában olvassa. A kiküldési válasz jobId értéket ad; a sor job_id, organization_id és plugin_id értéket. Az eredmény- és hibaoszlopok: result, error, error_code és error_troubleshooting. A completed és a failed végállapot. A timed_out, cancelled és system_failure a takarítótól származik, és egy későn érkező eredmény még módosíthatja őket. Az a kliens, amely ezek bármelyikét értelmezhetetlennek tekinti, olyan sorokat utasít el, amelyeket a platform minden nap ír.
A jóváhagyási visszatartás
A approval értéket deklaráló manifesztképesség a kiküldéskor visszatartásra kerül. Ekkor a 202 status: "awaiting_approval" értéket ad, és tartalmaz egy waitpointId elemet a manifesztben megadott indoklással. A futás addig visszatartva marad, amíg egy megnevezett személy döntést nem hoz róla. A uno.approve és a uno.resolveWaitpoint a bérlőt és a hívót szereplőként küldi, és az ellenőrzött hívótól eltérő személy döntése elutasításra kerül. A jóváhagyás egyszer engedi el a feladatot, és újra lefuttatja a kiküldési ellenőrzéseket; az elutasítás lezárja failed állapottal. A második döntés elutasításra kerül, ahogyan a visszatartás lejárta utáni döntés is. Ha a terméke megköveteli, hogy a jóváhagyó más személy legyen, mint a javaslattevő, ezt a döntést hozó útvonalon kényszerítse ki: a platform mindkettőt rögzíti.
A visszatartott feladatot visszatartottként jelenítse meg. Ne mondja egy személynek, hogy a kattintása elengedte, amíg a futási sor ezt nem mutatja.
AI: preferenciák a képesség (skill) sorában, és egyetlen olvasás
A plugin soha nem hív modellt. Ha egy manifesztképességnek szüksége van rá (llm_only vagy tool_using, core vagy verified bizalmi szinten), Ön a nyilvántartási sorában fogalmazza meg a preferenciáit, az útválasztó pedig a szervezet saját készletéből dönt:
{
"execution_config_skill": {
"preferredProvider": "gemini",
"capabilityProfile": { "needsToolUse": true, "dataResidency": "eu_only" }
}
}A preferredProvider és a preferredModel olyan kívánságok, amelyeket az útválasztó csak akkor teljesít, ha a szervezetnél az adott szolgáltató engedélyezve van és hitelesítő adatokkal rendelkezik. A capabilityProfile szűr, és soha nem választ; a dataResidency értéke (eu_only, us_only vagy any) kemény megkötés, amelyet az útválasztó vagy teljesít, vagy elutasít. Általában az a helyes, ha mindet elhagyja. A modelOverride azoknak a ritka képességeknek létezik, amelyeknek egyetlen pontos modellre van szükségük, és hatástalanná teszi a mellette álló kívánságokat; én kerülném, hacsak a képesség nem értelmetlen bármely más modellen.
Ha a felületének meg kell mutatnia, melyik modellt használná az útválasztó, olvassa ki, ne jósolja meg:
import { createAIRouteClient } from "@adverant-nexus/plugin-sdk/runtime/ai-route";A createAIRouteClient(...).effectiveRoute() az AI Provider Router egyetlen jóváhagyott lekérdezése. Átveszi az átjáró címét, a hívó saját bearer tokenjét és a platform slugját, és nem küld AI-kérést. Visszaadja a szolgáltatót és a modellt, a házirend által engedélyezett szolgáltatókat, valamint azt, hogy a kiválasztott végpont local vagy external módon fut-e. Ha az útvonal nem használható, az útválasztó szöveges elutasítását adja vissza (NO_PROVIDER_FOR_ROLE, MODEL_CAPABILITY_UNAVAILABLE vagy NO_MODEL_FOR_ROLE_AND_PROVIDER, a megoldással együtt), soha nem alapértelmezett modellt. Mutassa meg ezt az elutasítást a személynek; a szervezete konfigurációja szól belőle.
Licencellenőrzések
Három mechanizmus ellenőrzi a licencelést, három szinten.
Licencet megnevező jogosultság. A legegyszerűbb. A manifesztben egy jogosultság licence: "<feature>" értéket hordoz, és az őr, mielőtt bármely szerepkört beolvasna, a hívó saját tokenjével megkérdezi az identitásszolgáltatást, hogy a szervezet licence tartalmazza-e. Építse fel az őrt egy olvasóval:
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 }) },
});Az a licenc, amely nem tartalmazza a funkciót, mindenkit LICENCE_LOCKED kóddal utasít el, megnevezve, mi tartalmazza, és közölve, hogy a szervezet tulajdonosai és rendszergazdái bekapcsolhatják. Az olvashatatlan licenc UNHANDLED_ERROR kóddal utasít el: egy zárolt funkció soha nem kerül kiszolgálásra azért, mert a licenc elérhetetlen volt. A válaszok szervezetenként és funkciónként 30 másodpercig tárolódnak.
A termékkapu. A runtime/product-gate csomagból származó createProductGate({ baseUrl, product }) megkérdezi a jogosultság-ellenőrzést, hogy a hívó szervezete egyáltalán rendelkezik-e az Ön termékével, és a middleware() a hatókörőr után fut. A negatív ítélet ENTITLEMENT_DENIED; az elérhetetlen ellenőrzés ENTITLEMENT_UNREACHABLE, és a kapu soha nem keveri össze a kettőt.
Maga a licencdokumentum. Az a kód, amelynek magának kell döntenie az aláírt licenc alapján, például egy szakterületi csomag zárt modulja, a runtime/licence-document csomagból származó verifyLicenceDocument(docText, opts) függvényt használja. Ez tiszta függvény: nincs hálózati hívás, környezeti változó vagy fájl. Mindkét aláírást ellenőrzi a build által hordozott bizalmi gyökerekkel szemben, és egy állapotot ad vissza (VALID, WARN, GRACE, RESTRICT, TERMINATE vagy ABSENT) a jogosultságokkal, kiegészítőkkel és szakterületi csomagokkal együtt. Ezután a licenceAllows(verdict, featureGroup, action, tenantId?) megmondja, hogy egy csoport alatt use vagy provision műveletet végezhet-e. A RESTRICT engedélyezi a use műveletet, és a provision kérdésre LICENCE_LOCKED választ ad, így a futó munka folytatódik, és semmi új nem indul.
Tesztelés
A sablon tesztjei mutatják a mintát; ezek a mögötte álló eszközök.
Hatókör-utánzatok. Egyszer építse fel a feloldott hatókör tesztdublőrét a test/scope-fakes.ts fájlban, és injektálja mindenhová, a hiányzó esetekkel együtt: nincs egység, nincs token, nulla szervezetű token. Az elutasítási útvonalak maguk a termék.
Hamis kiküldési átvitel. A UnoClient a fetch, now és sleep elemeket fogadja, így egy egységteszt soha nem éri el a hálózatot. Ellenőrizze a boríték mezőit, a 202 alakját, a végállapotú sorig tartó lekérdezést annak organization_id értékével, valamint azt, hogy egy másik bérlőhöz tartozó sor elvetésre kerül.
Valódi Postgres. Egy hamis lekérdezőfüggvény egy SQL-karakterláncot igazol. Azt nem tudja igazolni, hogy a kényszerített sorszintű biztonság érvényben marad, vagy hogy a fájlok a migrátorhoz hasonlóan sorrendben kerülnek alkalmazásra. A testing/ephemeral-postgres elindít egy eldobható szervert, és ugyanazt a nexus-migrate futtatást végzi, amelyet az éles környezet:
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 (folyamatos integráción) kívül egy Postgres-szerver nélküli gép minden adatbázis-esetet név szerint, a megoldással együtt kihagy, és sosem jelez zöldet. CI-ban ugyanez a hiány a tesztcsomag elbukását okozza (EPHEMERAL_POSTGRES_UNAVAILABLE_IN_CI), mert egy kihagyott sorszintű biztonsági teszt olyan zöld kapu, amely semmit sem mért. A szerver legfeljebb 180 másodpercig vár az indulásra, és egy felügyeleti folyamat leállítja, amikor a tesztfolyamat megszűnik.
Az izolációs tesztkörnyezet. A testing/isolation-harness csomagból származó runIsolationHarness(target) beolvassa az alkalmazása által csatolt összes útvonalat, és mindegyiket megtámadja egy másik szervezet adminisztrátoraként és egy kollégaként. Ezután ismét támad úgy, hogy a kódszintű védelem el van távolítva, az adatbázis-szintű védelem el van távolítva, illetve mindkettő. Egy útvonal csak akkor PROVEN, ha a támadás bármelyik védelem jelenlétében kudarcot vall, mindkettő eltávolításával pedig eléri az áldozat adatait, így Ön tudja, hogy a teszt egyáltalán képes észlelni a szivárgást. Minden útvonal deklarált lekérdezését és példatörzsét küldi, így az üres kérést elutasító útvonal is elérhető. Rögzítse a ledgerOf(report) értéket egy tesztben, és buktassa el a defectsOf(report) esetén.
Regisztráció: a manifesztumtól a képesség-nyilvántartásig (skill registry)
A manifest skilljei egyetlen úton jutnak el a skill-nyilvántartásba:
manifest.skills[] → compileRegistry(manifest) → POST /api/v1/plugins/sync
A compileRegistry egy validált manifestből előállítja a nexus.plugin-sync/v1 törzset. A sablon ezt importáláskor végzi el, így egy érvénytelen manifest a build elbukását okozza:
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" } ]
}A szinkronizálás deklaratív: minden alkalommal a teljes skillkészletet küldje el, a kihagyott skill pedig letiltásra kerül, előzményei megőrzésével. Szigorú: az ismeretlen mező, egy másik szint mezője vagy egy null elutasításra kerül, az összes szabálysértés együtt, egyetlen 400 SYNC_CONTRACT_VIOLATION válaszban érkezik vissza, és amíg akár egy is fennáll, semmi sem kerül kiírásra. Skillenként egy nyilvántartási sort ír, a névtérrel ellátott feladattípus szerint kulcsolva, amely tartalmazza a diszpécser által olvasott összes oszlopot, így a skill abban a pillanatban futtatható, amikor a szinkronizálás 200 választ ad.
A plugin a hitelesített hívó, sosem egy törzsmező. A szinkronizálást a plugin saját munkaterheléséből hívja mTLS-en keresztül (kölcsönös TLS: Transport Layer Security mindkét végponton tanúsítvánnyal). A Skills Engine beolvassa a munkaterhelés klienstanúsítványát, amelynek SPIFFE-identitása (spiffe://<trust-domain>/ns/<namespace>/sa/<service-account>) megnevezi a névteret és a szolgáltatásfiókot, és kikeresi az adott névtérhez rögzített plugint és tulajdonos szervezetet. A törzsben lévő pluginId értéknek egyeznie kell; ez ellenőrzés, nem kiválasztó. Minden sor ezzel a pluginnal és szervezettel kerül kiírásra.
| Állapot | Kód | Jelentés |
|---|---|---|
| 200 | {contract, pluginId, version, created, updated, unchanged, disabled, skills} |
|
| 400 | SYNC_CONTRACT_VIOLATION |
Minden szabálysértés a violations[] listában; semmi sem került kiírásra |
| 401 | UNAUTHORIZED |
Hibás vagy hiányzó szolgáltatáskulcs |
| 401 | CALLER_IDENTITY_UNVERIFIED |
Nincs olvasható klienstanúsítvány-identitás |
| 403 | DELIVERY_IDENTITY_MISSING |
A hívó névtér egyetlen pluginhoz sem tartozik |
| 403 | PLUGIN_ID_MISMATCH |
A törzs egy másik plugint nevez meg |
| 409 | REGISTRY_CONFLICT |
Egy feladattípus máshoz tartozik, vagy a szinkronizáláson kívül lett regisztrálva; semmi sem került kiírásra |
Buktassa el a telepítési lépést minden, 200 értéktől eltérő állapot esetén. Semmilyen más állapot nem jelenti azt, hogy a skilljei regisztrálva vannak.
Bevezetés (onboarding)
A bevezetés tíz sorrendbe rendezett lépésben fut, amelyek mindegyike külön-külön újrafuttatható, megszakítható vagy visszagörgethető:
- A tároló klónozása és validálása.
- A manifest elemzése.
- Biztonsági problémák keresése.
- Az image felépítése.
- Feltöltése a telepítés registryjébe.
- Tartománynevek beállítása.
- Telepítés a telepítés kiadási csatornáin keresztül.
- Várakozás az állapotellenőrzésre.
- A plugin regisztrálása.
- A fejlesztő értesítése.
Telepítés előtt öt megfelelőségi ellenőrzés fut a manifesten és a felépített image-en: a manifest elemezhető és tartalmazza a kötelező mezőket; minden deklarált útvonal valódi, regisztrált útvonal; a plugin a saját sémájának tulajdonosa, és azon kívül semmit sem ír; az erőforrásigények deklaráltak és a határokon belül vannak; és az image rendelkezik működő állapotkezelővel. Az indításkor önmagát regisztráló plugin ugyanezt a szerződést saját hatáskörében futtatja, így az ellenőrzések a pipeline helyett az ő CI-jává válnak. Bármelyik kihagyása nem rövidíti le a bevezetést; csupán futásidőre helyezi át a hibát.
A manifestben megadott arculati elemeket a rendszer tartomány alapján, hitelesítés nélkül szolgálja ki, mivel a bejelentkezési oldalnak szüksége van rájuk, mielőtt bárki hitelesítő adattal rendelkezne. A branding teljes tartalmát kezelje nyilvánosként.
GATE_CANNOT_BE_SKIPPED hibával elutasításra kerül.Mit nem végez el Ön helyett a futtatókörnyezet
A futtatókörnyezet szigorúan biztosítja az izolációt, a feladatkiosztást és a modellhozzáférést. Nem teszi helyessé a termékének logikáját, és nem teszi gyorssá a lassú lekérdezést: minden utasítás egy kötött tranzakción belül fut, a manifest db blokkjában deklarált időkorlátokkal, és a statementTimeoutMs értéket túllépő utasítás megszakításra kerül, nem várakozik rá a rendszer. Ennek megfelelően méretezze a lekérdezéseit. Emellett a jóváhagyási várakoztatás, az olvasási hely és a licencolvasó mind egy további körutat vagy tranzakciót jelent. Az én anomália-felülvizsgálati pluginomnál a licencellenőrzés kérésenként néhány ezredmásodpercet adott hozzá, amíg 30 másodperces memóriája fel nem melegedett, ami tisztességes ár volt azért, hogy soha ne szolgáljon ki zárolt funkciót.

