BejelentkezésBemutató kérése

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

21 perc olvasási idő

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 runs

CI-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ő:

  1. A tároló klónozása és validálása.
  2. A manifest elemzése.
  3. Biztonsági problémák keresése.
  4. Az image felépítése.
  5. Feltöltése a telepítés registryjébe.
  6. Tartománynevek beállítása.
  7. Telepítés a telepítés kiadási csatornáin keresztül.
  8. Várakozás az állapotellenőrzésre.
  9. A plugin regisztrálása.
  10. 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.

Környezetek és előléptetés
Környezetek és előléptetés
A Környezetek és előléptetés funkció minden kiadást a fejlesztői térből a staging környezeten át egy pilot egységbe, majd az összes egységbe juttat, minden kapuval és azok állapotával egyetlen oldalon. A kaput kihagyó előléptetés GATE_CANNOT_BE_SKIPPED hibával elutasításra kerül.
Csatornák és telepítések
Csatornák és telepítések
A Csatornák és telepítések nézet megmutatja, melyik egység melyik verziót futtatja, a hibaarányokat darabszámként, és sosem tartalomként. Egyetlen egység visszagörgetése felülvizsgált módosítás, amely csak az adott egységet érinti.

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.