Verzia 1.0.0-alpha.1najnovšia
Kapitola 2.22
Behové prostredie zásuvných modulov (plugin runtime)
Moduly SDK (sady nástrojov na vývoj softvéru), na ktorých beží váš zásuvný modul, od strážcu rozsahu (scope guard) a databázového oplotenia až po dispečing UNO, čítanie trasy AI (umelej inteligencie) a kontroly licencií. Následne testovanie oproti reálnej databáze, registrácia vašich zručností a úvodné nastavenie (onboarding).
Táto stránka bola preložená pomocou AI z anglického originálu. V prípade akýchkoľvek nejasností je rozhodujúca anglická verzia stránky. Prečítať túto stránku v angličtine

Behová polovica SDK (súpravy na vývoj softvéru) je súbor modulov pod @adverant-nexus/plugin-sdk/runtime/* plus pomocné testovacie nástroje pod testing/*. Importujete ich; znova ich neimplementujete. V tom spočíva celá myšlienka a trvalo mi jedno zamietnuté posúdenie kódu, kým som to začal brať vážne: poznámka recenzenta k mojej vlastnoručne napísanej kontrole rozsahu v prvom zásuvnom module mala jediný riadok: „SDK to už obsahuje a tá vaša akceptuje výzvový token MFA (viacfaktorovej autentifikácie) ako reláciu“.
Táto kapitola sleduje požiadavku naprieč bežiacim zásuvným modulom tak, ako ju prepája plnohodnotná šablóna služby: strážca rozsahu, databázová bariéra, jediný povolený prechod cez hranicu, odoslanie cez UNO, čítanie smerovania AI (umelej inteligencie) a kontroly licencií. Následne sa venuje testovaniu, registrácii zručností z vášho manifestu a krokom nasadenia (onboardingu).
Rozsah (scope): jeden strážca na framework
Každá cesta /api obsahuje strážcu rozsahu. Ten overí doručiteľský (bearer) token, odvodí z neho tri osi (nájomca, vlastník, jednotka), odmietne telo požiadavky, ktoré uvádza nájomcu, uplatní oprávnenie cesty z registra manifestu a až potom povolí spustenie obslužnej rutiny (handlera). SDK dodáva jeden adaptér pre každý framework, všetky z @adverant-nexus/plugin-sdk/runtime/scope a všetky prijímajú rovnaké možnosti.
| Framework | Adaptér |
|---|---|
| Express | scopeMiddleware |
| Fastify | requireScope, ako preHandler |
| Next | withScope, obaľujúci obslužnú rutinu; obslužnej rutine Next sa neoznamuje jej cesta, preto ju withScope prijíma ako tretí argument |
Tu je skrátené prepojenie pre Express zo šablóny. Overovač pochádza z SDK a vyžaduje, aby token spĺňal formát relácie služby identít: iba HS256; vyžadujú sa iss, exp, iat a jti; životnosť najviac jedna hodina; a ako relácia sa nepripúšťa žiadny výzvový token MFA, token zosobnenia (impersonácie) ani zdrojový token OAuth (otvorený štandard pre delegovanú autorizáciu).
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)) });
});Strážca oprávnení uplatňuje oprávnenie cesty v štyroch krokoch. Rola v zozname never daného oprávnenia zamietne prístup s kódom AUTHORITY_EXCEEDED a slovami barred, pričom žiadne pridelené miesto (seat) to neodblokuje. Rola v roles prístup povolí, a ak oprávnenie vyžaduje seat: true, vyžaduje sa aj aktívne miesto. V opačnom prípade prístup povolí aktívne miesto, ktoré je nositeľom daného oprávnenia. Inak je požiadavka zamietnutá s AUTHORITY_EXCEEDED a uvedením osôb, ktoré by mohli miesto udeliť. Ak strážcovi poskytnete úložisko (rights: { manifest, store: { pool, schema } }), bude čítať miesta v rámci vlastného rozsahu volajúceho; oprávnenie, ktoré uvádza licence, potrebuje aj čítačku licencií, ktorej sa venujeme nižšie.
Vo vnútri obslužnej rutiny je scopeOf(req) jediným spôsobom, ako prečítať odvodený rozsah, a ak strážca neprebehol, vyvolá výnimku. Strážca zaregistrovaný na prefixe, ktorý beží pred priradením akejkoľvek cesty, odpovie kódom 500 MIDDLEWARE_ORDERING_ERROR; cesta, ktorú váš kód zaregistruje, no manifest ju nedeklaruje, odpovie kódom 500 UNHANDLED_ERROR. Oba prípady zlyhajú bezpečne (fail closed).
Cesty /internal v šablóne, ktoré volá platforma, používajú druhý režim. Servisný strážca skontroluje X-Service-Key v konštantnom čase a prevezme nájomcu z X-Organization-ID platformy, pričom odmietne MISSING_SERVICE_KEY, INVALID_SERVICE_KEY alebo MISSING_ORG_ID_HEADER. Pre podpísaný token platformy určený pre jednotlivé volania má SDK k dispozícii requireService (Fastify) a serviceMiddleware (Express), ktoré tiež kontrolujú, pre ktorú zručnosť a cestu bol token vydaný, a odmietnu token použitý dvakrát.
Databázová bariéra: tenantFence a withScopedTx
Každý príkaz voči tabuľke s vymedzeným rozsahom zostavuje bariéru a beží vo vnútri transakcie s vymedzeným rozsahom:
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) zostaví predikát a jeho parametre z odvodeného rozsahu. Pre osobné tabuľky odovzdajte owner; vynechajte ho pre organizačné artefakty, kde vlastník predstavuje pôvod (provenienciu). Keď už príkaz obsahuje parametre, startIndex určí bariére, odkiaľ má číslovať. Príkaz insert nikdy neprijíma osi ako vstup: zapisuje scope.tenant, scope.owner a scope.unit z rozsahu.
withScopedTx naviaže všetky tri osi pre jednu transakciu prostredníctvom jedinej viazacej funkcie schémy a následne spustí vašu spätnú väzbu (callback). Druhé naviazanie v tej istej transakcii vyvolá SCOPE_ALREADY_BOUND (500: váš kód vykonal naviazanie dvakrát; volajúci neurobil nič zlé). Chýbajúci alebo nulový nájomca či vlastník vyvolá SCOPE_PREDICATE_INVALID (403). Nastavenie je lokálne pre danú transakciu, takže zdieľané (pooled) pripojenie nemôže preniesť jedného nájomcu do ďalšej požiadavky.
Dve súrodenecké funkcie pokrývajú prípady, ktoré nie sú požiadavkou osoby. withTenantScopedTx naviaže nájomcu a jednotku bez vlastníka pre riadky, ktoré číta stroj (register zariadení), a odmietne rozsah, ktorý obsahuje vlastníka. maintenanceScope(reason) prinúti celoorganizačnú operáciu výslovne deklarovať svoj účel predtým, než sa otvorí transakcia vlastníka. Kódová bariéra a vynútené zabezpečenie na úrovni riadkov (RLS) sú dva mechanizmy pre jeden zákon; kontrola pri štarte odmietne počúvať, kým databáza nedokáže, že ten druhý platí (inak DB_ROLE_BYPASSES_ISOLATION).
Každé odmietnutie predstavuje jeden riadok
Šablóna inštaluje ešte jeden kus middlewaru, a to raz, medzi analyzátor tela (body parser) a smerovače: účtovnú knihu zamietnutí.
import { recordRefusals } from "@adverant-nexus/plugin-sdk/runtime/refusal-ledger";
app.use(express.json({ limit: "256kb" }));
app.use(recordRefusals({ pool, schema: SCHEMA }));Obaľuje odpoveď tak, aby sa každé zamietnutie, ktoré osoba dostane – či už od strážcu oprávnení, obslužnej rutiny alebo úložiska –, zapísalo do tabuľky refusal vašej schémy vo vnútri vlastnej transakcie s vymedzeným rozsahom danej osoby ešte pred odoslaním tela odpovede. Anonymný stav 401 nezapíše nič. Ak riadok nemožno zapísať, odpoveď sa zmení na UNHANDLED_ERROR: „nie“, ktoré produkt nedokáže zaznamenať, sa neodošle, akoby zaznamenané bolo. Pri štarte sa spustí assertRefusalLedger, aby sa overilo, že tabuľka dokáže prijať riadok knihy zamietnutí, a úložisko môže zavolať noteSubject({ recordId, isDemo }), aby každé zamietnutie uvádzalo záznam, ktorého sa týkalo. Keď sa zákazník opýta, prečo bol niekto minulý utorok odmietnutý, odpoveďou je dopyt, nie dohad.
Jediný priechod: zaznamenané udelenie prístupu len na čítanie
Keď jeden z vašich zákazníkov vykonáva prácu pre iného a ten druhý ju môže kontrolovať, existuje jeden schválený spôsob prechodu cez hranicu. Organizácia, ktorá vlastní riadky, zaznamená udelenie prístupu (grant). Organizácia čitateľa vpustí osobu prostredníctvom miesta s oprávnením granted.read, ktoré musí uvádzať owner a admin v never. Čítanie beží ako šiesta databázová rola, čitateľské miesto (read seat), ktoré môže vykonávať výber (SELECT) iba z tabuliek uvedených v databases[].granted:
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 najprv zapíše nahliadnutie u vlastného nájomcu čitateľa a potom naviaže čitateľské miesto na udelenie prístupu, čo zapíše nahliadnutie u nájomcu držiteľa. Vlastná politika databázy skontroluje, či udelenie prístupu uvádza organizáciu čitateľa, pokrýva danú tabuľku, už začalo, ešte neskončilo a nebolo odvolané, a či táto transakcia zapísala svoje nahliadnutie. Čítanie, ktoré nahliadnutie preskočí, neuvidí nič. Pri štarte assertSeatAtBoot(seatPool, schema) skontroluje, či fond pripojení (pool) otvorený z seat.url je skutočne len týmto miestom a ničím viac, inak ho odmietne s DB_SEAT_ROLE_INVALID.
Dispečing cez UNO
Všetky výpočty prechádzajú cez jedného klienta, zostaveného v jednom súbore, s uzavretým zoznamom povolení (allow-list):
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,
});
}Zoznam povolení je zámerne konštantou na úrovni modulu. Ak by ho operátor mohol rozšíriť z konfigurácie, cesta by sa stala odosielacím proxy serverom pre celý register. Vlastný test šablóny overuje, že zoznam uvádza presne tie typy úloh, do ktorých sa kompiluje manifest.
Obálka
Odoslanie (dispatch) nesie vo svojom povinnom jadre šesť polí. Klient vyplní nájomcu a aktéra z overeného rozsahu, nikdy nie z požiadavky:
| Pole | Čo obsahuje |
|---|---|
jobType |
Typ úlohy s menným priestorom, <plugin name>.<skill id> |
organizationId |
Nájomca, z rozsahu |
userId |
Aktér, z rozsahu, pre audit a fakturáciu |
inputParams |
Vstup zručnosti. Nikdy nenesie ID nájomcu; taký, ktorý ho nesie, je pri odoslaní odmietnutý |
priority |
critical, high, normal alebo low |
pluginId |
Váš manifest name. Každé odoslanie deklaruje svoj pôvodný zásuvný modul |
Voliteľné polia zahŕňajú correlationId (UUID – univerzálne jedinečný identifikátor, prípadne sa vygeneruje nový) a callbackUrl, ktoré potrebuje zručnosť plugin_queue, aby pracovný proces (worker) vedel, kam má odoslať svoj výsledok.
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, potom dopytovanie (polling)
Každé odoslanie je zaradené do frontu. Odpoveďou je vždy 202 s identifikátormi (jobId, runId, traceId, status), nikdy nie výsledok. Výsledok prichádza z dopytovania (pollingu) úlohy alebo z vašej spätnej väzby (callbacku). uno.peek(jobId, { scope }) ho prečíta raz a awaitJob sa dopytuje až do koncového stavu; obe funkcie odosielajú nájomcu z overeného rozsahu a obe kontrolujú organization_id vráteného riadka voči nájomcovi volajúceho na vašej strane sieťového volania, pričom nezhodu odmietnu s SCOPE_REFUSED.
Čítajte riadok behu v jeho vlastnom zápise. Odpoveď na odoslanie uvádza jobId; riadok uvádza job_id, organization_id a plugin_id. Stĺpce výsledku a zlyhania sú result, error, error_code a error_troubleshooting. Stavy completed a failed sú koncové. Stavy timed_out, cancelled a system_failure pochádzajú zo zberača (reapera) a oneskorený výsledok ich ešte môže opraviť. Klient, ktorý ktorýkoľvek z nich považuje za nespracovateľný, odmieta riadky, ktoré platforma zapisuje každý deň.
Pozastavenie na schválenie
Zručnosť manifestu, ktorá deklaruje approval, je pri odoslaní pozastavená. Odpoveď 202 potom uvádza status: "awaiting_approval" a nesie waitpointId s dôvodom, ktorý uviedol manifest. Beh zostáva pozastavený, kým o ňom nerozhodne menovaná osoba. uno.approve a uno.resolveWaitpoint odošlú nájomcu a volajúceho ako aktéra, pričom rozhodnutie urobené niekým iným než overeným volajúcim sa odmietne. Schválenie uvoľní úlohu raz a znova spustí kontroly odoslania; zamietnutie ju ukončí so stavom failed. Druhé rozhodnutie sa odmietne a rovnako aj rozhodnutie po vypršaní platnosti pozastavenia. Ak váš produkt vyžaduje, aby schvaľovateľ bol inou osobou ako navrhovateľ, vynúťte to v ceste, ktorá rozhoduje: platforma zaznamenáva oboch.
Vykreslite pozastavenú úlohu ako pozastavenú. Nehovorte osobe, že jej kliknutie úlohu uvoľnilo, kým to nepotvrdí riadok behu.
AI: požiadavky (wishes) v riadku zručnosti a jedno čítanie
Váš zásuvný modul nikdy nevolá model. Keď ho zručnosť manifestu potrebuje (llm_only alebo tool_using, na úrovni dôvery core alebo verified), vyjadríte preferencie v jej riadku registra a smerovač rozhodne z vlastného fondu organizácie:
{
"execution_config_skill": {
"preferredProvider": "gemini",
"capabilityProfile": { "needsToolUse": true, "dataResidency": "eu_only" }
}
}preferredProvider a preferredModel sú želania, ktoré smerovač rešpektuje len vtedy, keď má organizácia daného poskytovateľa povoleného a má preňho prihlasovacie údaje. capabilityProfile filtruje a nikdy nevyberá; jeho dataResidency (eu_only, us_only alebo any) je tvrdé obmedzenie, ktoré smerovač buď splní, alebo odmietne. Vynechať všetky z nich je zvyčajne správne. modelOverride existuje pre zriedkavú zručnosť, ktorá potrebuje jeden presný model, a spôsobuje, že želania vedľa neho sú neúčinné; vyhol by som sa mu, pokiaľ zručnosť nedáva zmysel na žiadnom inom modeli.
Keď vaše rozhranie potrebuje zobraziť, ktorý model by smerovač použil, prečítajte to, nepredpovedajte to:
import { createAIRouteClient } from "@adverant-nexus/plugin-sdk/runtime/ai-route";createAIRouteClient(...).effectiveRoute() je jediné schválené čítanie smerovača AI Provider Router. Prijíma adresu brány, vlastný doručiteľský (bearer) token volajúceho a identifikátor (slug) vašej platformy, pričom neodosiela žiadnu požiadavku na AI. Vráti poskytovateľa a model, poskytovateľov povolených politikou a informáciu, či vybraný koncový bod beží ako local alebo external. Keď cesta nie je použiteľná, vráti zamietnutie smerovača slovne (NO_PROVIDER_FOR_ROLE, MODEL_CAPABILITY_UNAVAILABLE alebo NO_MODEL_FOR_ROLE_AND_PROVIDER, aj s nápravou), nikdy nie predvolený model. Zobrazte toto zamietnutie danej osobe; hovorí tým konfigurácia jej vlastnej organizácie.
Kontroly licencií
Licencovanie kontrolujú tri mechanizmy, na troch úrovniach podrobnosti.
Oprávnenie, ktoré uvádza licenciu. Najjednoduchší spôsob. V manifeste nesie oprávnenie položku licence: "<feature>" a strážca sa s vlastným tokenom volajúceho opýta služby identít, či ju licencia organizácie obsahuje, ešte predtým, než sa prečíta akákoľvek rola. Zostavte strážcu s čítačkou:
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 }) },
});Licencia, ktorá danú funkciu neobsahuje, odmietne každého s kódom LICENCE_LOCKED, pričom uvedie, čo ju obsahuje, a oznámi, že vlastníci a administrátori organizácie ju môžu zapnúť. Licencia, ktorú nemožno prečítať, odmietne prístup s UNHANDLED_ERROR: uzamknutá funkcia sa nikdy neposkytne len preto, že licencia bola nedostupná. Odpovede sa pamätajú po dobu 30 sekúnd pre každú organizáciu a funkciu.
Produktová brána. createProductGate({ baseUrl, product }) z runtime/product-gate sa opýta kontroly nárokov (entitlement check), či organizácia volajúceho vôbec vlastní váš produkt, a jej middleware() beží po strážcovi rozsahu. Negatívny verdikt je ENTITLEMENT_DENIED; nedostupná kontrola je ENTITLEMENT_UNREACHABLE, pričom brána nikdy nezamieňa jedno za druhé.
Samotný licenčný dokument. Kód, ktorý sa musí rozhodnúť sám na základe podpísanej licencie, ako napríklad uzavretý modul doménového balíka, používa verifyLicenceDocument(docText, opts) z runtime/licence-document. Je to čistá funkcia: žiadne sieťové volanie, žiadna premenná prostredia, žiadny súbor. Skontroluje oba podpisy voči koreňom dôveryhodnosti, ktoré zostava (build) nesie, a vráti stav (VALID, WARN, GRACE, RESTRICT, TERMINATE alebo ABSENT) spolu s udeleniami prístupu, doplnkami a doménovými balíkmi. licenceAllows(verdict, featureGroup, action, tenantId?) potom určí, či môžete vykonať use alebo provision v rámci skupiny. RESTRICT povoľuje use a na provision odpovedá s LICENCE_LOCKED, takže bežiaca práca pokračuje a nič nové sa nespustí.
Testovanie
Testy šablóny ukazujú tento vzor; toto sú nástroje, ktoré za ním stoja.
Napodobeniny rozsahu (scope fakes). Zostavte dvojníka odvodeného rozsahu raz, v test/scope-fakes.ts, a vstreknite ho všade, vrátane prípadov neprítomnosti: žiadna jednotka, žiadny token, token s nulovou organizáciou. Cesty zamietnutia sú samotným produktom.
Falošný transport odoslania. UnoClient prijíma fetch, now a sleep, takže jednotkový (unit) test sa nikdy nedotkne siete. Overte polia obálky, tvar 202, dopytovanie až po koncový riadok s jeho organization_id a to, že riadok pre iného nájomcu sa zahodí.
Skutočný Postgres. Falošná dopytovacia funkcia dokazuje správnosť reťazca SQL. Nedokáže však preukázať, že vynútené zabezpečenie na úrovni riadkov platí alebo že sa súbory aplikujú v poradí ako v migrátore. testing/ephemeral-postgres spustí jednorazový server a vykoná tie isté nexus-migrate, aké bežia v produkcii:
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 runsMimo CI (kontinuálnej integrácie) stroj bez servera Postgres preskočí každý databázový prípad podľa názvu s uvedením nápravy, nikdy nie so zeleným stavom. V CI tá istá neprítomnosť spôsobí zlyhanie celej sady (EPHEMERAL_POSTGRES_UNAVAILABLE_IN_CI), pretože preskočený test zabezpečenia na úrovni riadkov je zelená brána, ktorá nič neodmerala. Server čaká na spustenie až 180 sekúnd a strážny proces (watchdog) ho zastaví, keď testovací proces skončí.
Izolačný postroj (harness). runIsolationHarness(target) z testing/isolation-harness prečíta každú cestu, ktorú vaša aplikácia pripojí, a zaútočí na každú z nich ako administrátor inej organizácie a ako kolega. Potom zaútočí znova s odstránenou kódovou bariérou, s odstránenou databázovou bariérou a s odstránenými oboma. Cesta má stav PROVEN iba vtedy, keď útok zlyhá pri zapnutej ktorejkoľvek z bariér a dostane sa k údajom obete pri odstránení oboch, takže viete, že test vôbec dokáže odhaliť únik. Odosiela deklarovaný dopyt a príklad tela každej cesty, takže sa dosiahne aj cesta, ktorá odmieta prázdnu požiadavku. Pripnite ledgerOf(report) v teste a nastavte zlyhanie pri defectsOf(report).
Registrácia: od manifestu po register zručností
Zručnosti z vášho manifestu sa do registra zručností dostanú jedinou cestou:
manifest.skills[] → compileRegistry(manifest) → POST /api/v1/plugins/sync
compileRegistry premení validovaný manifest na telo nexus.plugin-sync/v1. Šablóna to robí pri importe, takže neplatný manifest spôsobí zlyhanie zostavenia (buildu):
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" } ]
}Synchronizácia je deklaratívna: zakaždým odošlite celú sadu zručností a vynechaná zručnosť sa deaktivuje, pričom jej história zostane zachovaná. Je prísna: neznáme pole, pole z inej úrovne alebo null sa odmietne, všetky porušenia sa vrátia spolu v jednom 400 SYNC_CONTRACT_VIOLATION a kým existuje čo i len jedno, nič sa nezapíše. Pre každú zručnosť zapíše jeden riadok registra, kľúčovaný podľa typu úlohy s menným priestorom, ktorý nesie každý stĺpec čítaný dispečerom, takže zručnosť je spustiteľná v momente, keď synchronizácia odpovie 200.
Autentifikovaným volajúcim je zásuvný modul, nikdy nie pole v tele požiadavky. Volajte synchronizáciu z vlastnej pracovnej záťaže (workloadu) vášho zásuvného modulu cez mTLS (vzájomné TLS: Transport Layer Security s certifikátom na oboch koncoch). Skills Engine prečíta klientsky certifikát vašej pracovnej záťaže, ktorého identita SPIFFE (spiffe://<trust-domain>/ns/<namespace>/sa/<service-account>) uvádza menný priestor a servisný účet, a vyhľadá zásuvný modul a vlastniacu organizáciu zaznamenanú pre daný menný priestor. Položka pluginId v tele sa musí zhodovať; je to kontrola, nie selektor. Každý riadok sa zapíše s týmto zásuvným modulom a organizáciou.
| Stav | Kód | Význam |
|---|---|---|
| 200 | {contract, pluginId, version, created, updated, unchanged, disabled, skills} |
|
| 400 | SYNC_CONTRACT_VIOLATION |
Každé porušenie uvedené v violations[]; nič sa nezapísalo |
| 401 | UNAUTHORIZED |
Chybný alebo chýbajúci servisný kľúč |
| 401 | CALLER_IDENTITY_UNVERIFIED |
Žiadna čitateľná identita klienta |
| 403 | DELIVERY_IDENTITY_MISSING |
Volajúci menný priestor nepatrí žiadnemu zásuvnému modulu |
| 403 | PLUGIN_ID_MISMATCH |
Telo uvádza iný zásuvný modul |
| 409 | REGISTRY_CONFLICT |
Typ úlohy je vlastnený inde alebo bol zaregistrovaný mimo synchronizácie; nič sa nezapísalo |
Nastavte zlyhanie kroku nasadenia (deploy) pri akomkoľvek inom stave ako 200. Žiadny iný stav neznamená, že vaše zručnosti sú zaregistrované.
Úvodné nastavenie (onboarding)
Nasadenie (onboarding) prebieha ako desať usporiadaných krokov, z ktorých každý možno samostatne znova spustiť, zrušiť alebo vrátiť späť (rollback):
- Naklonovanie repozitára a jeho validácia.
- Syntaktická analýza (parsovanie) manifestu.
- Skenovanie bezpečnostných problémov.
- Zostavenie obrazu (image).
- Odoslanie obrazu do registra inštalácie.
- Nastavenie jeho doménových mien.
- Nasadenie prostredníctvom kanálov vydaní danej inštalácie.
- Čakanie na kontrolu stavu (health check).
- Registrácia zásuvného modulu.
- Oboznámenie vývojára.
Pred nasadením prebehne voči manifestu a zostavenému obrazu päť kontrol zhody: manifest je syntakticky spracovateľný a obsahuje povinné polia; každá deklarovaná cesta je skutočnou zaregistrovanou cestou; zásuvný modul vlastní svoju schému a nezapisuje nič mimo nej; požiadavky na zdroje sú deklarované a v povolených medziach; a obraz má funkčnú obslužnú rutinu kontroly stavu. Zásuvný modul, ktorý sa registruje sám pri štarte, spúšťa ten istý kontrakt pod vlastnou autoritou, takže sa tieto kontroly stanú jeho vlastným CI namiesto CI potrubia (pipeline). Preskočenie ktorejkoľvek z nich neskráti nasadenie; len presunie zlyhanie do času behu (runtime).
Branding vo vašom manifeste sa poskytuje bez autentifikácie podľa domény, pretože prihlasovacia stránka ho potrebuje skôr, než má ktokoľvek prihlasovacie údaje. Považujte všetko v branding za verejné.
GATE_CANNOT_BE_SKIPPED.Čo behové prostredie neurobí za vás
Behové prostredie (runtime) nekompromisne stráži izoláciu, odosielanie úloh a prístup k modelom. Nespraví však vašu produktovú logiku správnou a ani neurobí pomalý dopyt rýchlym: každý príkaz beží vo vnútri viazanej transakcie s časovými limitmi, ktoré deklaruje blok db vášho manifestu, a príkaz, ktorý prekročí statementTimeoutMs, sa zruší, nečaká sa naň. Prispôsobte tomu veľkosť svojich dopytov. Pozastavenie na schválenie, čitateľské miesto a čítačka licencií navyše pridávajú sieťovú komunikáciu (round trip) alebo transakciu. V mojom zásuvnom module na kontrolu anomálií pridala kontrola licencie niekoľko milisekúnd na požiadavku, kým sa nezahriala jej 30-sekundová pamäť, čo bola férová cena za to, že sa nikdy neposkytne uzamknutá funkcia.

