PrisijungtiUžsisakyti pristatymą

2.22 skyrius

Įskiepių vykdymo aplinka

SDK (programinės įrangos kūrimo rinkinio) moduliai, kuriais remiasi jūsų įskiepis: nuo aprėpties sargo ir duomenų bazės užtvaros iki UNO dispečerio, DI (dirbtinio intelekto) maršruto nuskaitymo bei licencijų patikrinimų. Toliau – testavimas su tikra duomenų baze, jūsų įgūdžių registravimas ir įvedimas.

Šį puslapį iš originalo anglų kalba išvertė DI. Jei kas nors neaišku, remkitės puslapiu anglų kalba. Skaityti šį puslapį anglų kalba

21 min. skaitymo

Vykdymo laiko SDK (programinės įrangos kūrimo rinkinio) dalis yra modulių rinkinys, esantis @adverant-nexus/plugin-sdk/runtime/*, ir testavimo pagalbinės priemonės, esančios testing/*. Jūs juos importuojate, o ne kuriate iš naujo. Tai ir yra visa esmė, ir man prireikė vienos atmestos peržiūros, kad į tai pažiūrėčiau rimtai: recenzento pastaba apie ranka parašytą mano pirmojo įskiepio apimties patikrą buvo viena eilutė: „SDK tai jau turi, o jūsiškė priima MFA (daugiapakopio autentifikavimo) iššūkio prieigos raktą kaip seansą“.

Šiame skyriuje sekama užklausa per veikiantį įskiepį taip, kaip ją sujungia pilnos paslaugos šablonas: apimties apsauga, duomenų bazės užtvara, vienintelis leidžiamas perėjimas, išsiuntimas per UNO, DI (dirbtinio intelekto) maršruto nuskaitymas ir licencijos patikros. Toliau aptariamas testavimas, jūsų manifesto įgūdžių registravimas ir pradinės parengties žingsniai.

Aprėptis: po vieną sargą kiekvienam karkasui

Kiekvienas /api maršrutas turi apimties apsaugą. Ji patikrina nešėjo prieigos raktą, iš jo nustato tris ašis (nuomininką, savininką, padalinį), atmeta užklausos turinį, kuriame nurodytas nuomininkas, pritaiko maršruto teisę iš manifesto registro ir tik tada leidžia vykdyti apdorojimo funkciją. SDK pateikia po vieną adapterį kiekvienai sistemai, visus iš @adverant-nexus/plugin-sdk/runtime/scope ir visus priimančius tas pačias parinktis.

Sistema Adapteris
Express scopeMiddleware
Fastify requireScope, kaip preHandler
Next withScope, apgaubiantis apdorojimo funkciją; Next apdorojimo funkcijai nepranešamas jos maršrutas, todėl withScope jį priima kaip trečiąjį argumentą

Štai šablono Express sujungimas, sutrumpintas. Tikrintuvas yra SDK, ir jis reikalauja, kad prieigos raktas atitiktų tapatybės paslaugos seanso formatą: tik HS256; privalomi iss, exp, iat ir jti; galiojimo trukmė ne ilgesnė kaip valanda; ir joks MFA iššūkio, apsimetimo ar OAuth (atvirojo deleguoto įgaliojimo standarto) išteklių prieigos raktas nepriimamas kaip seansas.

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)) });
});

Teisių apsauga maršruto teisę pritaiko keturiais žingsniais. Vaidmuo, esantis teisės never sąraše, atmetamas su AUTHORITY_EXCEEDED ir barred žodžiais, ir jokia vieta to nepanaikina. Vaidmuo, esantis roles, įleidžiamas, kartu su aktyvia vieta, kai teisėje nurodyta seat: true. Kitu atveju įleidžia aktyvi vieta, turinti šią teisę. Kitu atveju užklausa atmetama AUTHORITY_EXCEEDED, nurodant asmenis, kurie galėtų suteikti vietą. Suteikite apsaugai saugyklą (rights: { manifest, store: { pool, schema } }), ir ji nuskaitys vietas pagal paties kviečiančiojo apimtį; teisei, kurioje nurodytas licence, taip pat reikalinga licencijos skaityklė, aptariama toliau.

Apdorojimo funkcijoje scopeOf(req) yra vienintelis būdas nuskaityti nustatytą apimtį, ir ji meta išimtį, jei apsauga nebuvo įvykdyta. Apsauga, užregistruota prefiksui ir vykdoma prieš atitinkant bet kurį maršrutą, atsako 500 MIDDLEWARE_ORDERING_ERROR; jūsų kodo užregistruotas maršrutas, kurio manifestas nedeklaruoja, atsako 500 UNHANDLED_ERROR. Abiem atvejais gedimas baigiasi uždarymu.

Šablono /internal maršrutai, kuriuos kviečia platforma, naudoja kitą režimą. Paslaugos apsauga pastovios trukmės palyginimu patikrina X-Service-Key ir nuomininką paima iš platformos X-Organization-ID, atmesdama MISSING_SERVICE_KEY, INVALID_SERVICE_KEY arba MISSING_ORG_ID_HEADER. Platformos pasirašytam kiekvieno kvietimo prieigos raktui SDK turi requireService (Fastify) ir serviceMiddleware (Express), kurie taip pat patikrina, kuriam įgūdžiui ir maršrutui prieigos raktas buvo išduotas, ir atmeta du kartus panaudotą prieigos raktą.

Duomenų bazės užtvara: tenantFence ir withScopedTx

Kiekvienas sakinys, vykdomas su apimties lentele, sudaro užtvarą ir vykdomas apimties transakcijoje:

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) iš nustatytos apimties sudaro predikatą ir jo parametrus. Asmeninėms lentelėms perduokite owner; organizacijos artefaktams, kuriuose savininkas nurodo kilmę, jo nenurodykite. Kai sakinys jau turi parametrų, startIndex nurodo užtvarai, nuo kurio numerio pradėti numeruoti. Įterpimas niekada nepriima ašių kaip įvesties: jis įrašo scope.tenant, scope.owner ir scope.unit iš apimties.

withScopedTx vienai transakcijai susieja visas tris ašis per vienintelę schemos susiejimo funkciją, tada vykdo jūsų atgalinio iškvietimo funkciją. Antras susiejimas toje pačioje transakcijoje sukelia SCOPE_ALREADY_BOUND (500: jūsų kodas susiejo du kartus; kviečiantysis nieko blogo nepadarė). Nesantis arba nulinis nuomininkas ar savininkas sukelia SCOPE_PREDICATE_INVALID (403). Nustatymas galioja tik transakcijoje, todėl telkinio ryšys negali perkelti vieno nuomininko į kitą užklausą.

Dvi giminingos funkcijos apima atvejus, kurie nėra asmens užklausa. withTenantScopedTx susieja nuomininką ir padalinį be savininko, eilutėms, kurias skaito mašina (įrenginių registrui), ir atmeta apimtį, kurioje yra savininkas. maintenanceScope(reason) reikalauja, kad visos organizacijos operacija aiškiai įvardytų, kas ji yra, prieš atidarant savininko transakciją. Kodo užtvara ir priverstinė eilučių lygio sauga yra du vieno dėsnio mechanizmai; paleidimo patikra atsisako priimti užklausas, kol duomenų bazė neįrodo, kad antrasis galioja (kitu atveju DB_ROLE_BYPASSES_ISOLATION).

Kiekvienas atmetimas tampa eilute

Šablonas vieną kartą, tarp užklausos turinio analizatoriaus ir maršrutizatorių, įdiegia dar vieną tarpinės programinės įrangos dalį: atsisakymų žurnalą.

import { recordRefusals } from "@adverant-nexus/plugin-sdk/runtime/refusal-ledger";

app.use(express.json({ limit: "256kb" }));
app.use(recordRefusals({ pool, schema: SCHEMA }));

Jis apgaubia atsakymą taip, kad kiekvienas asmens matomas atsisakymas – iš teisių apsaugos, apdorojimo funkcijos ar saugyklos – prieš išsiunčiant turinį būtų įrašytas į jūsų schemos refusal lentelę to paties asmens apimties transakcijoje. Anoniminis 401 nieko neįrašo. Jei eilutės įrašyti nepavyksta, atsakymas tampa UNHANDLED_ERROR: „ne“, kurio produktas negali užfiksuoti, nesiunčiamas taip, lyg būtų užfiksuotas. Paleidimo metu vykdoma assertRefusalLedger, kad būtų patikrinta, ar lentelė gali priimti žurnalo eilutę, o saugykla gali iškviesti noteSubject({ recordId, isDemo }), kad kiekviename atsisakyme būtų nurodytas įrašas, kurio jis lietė. Kai klientas klausia, kodėl kažkam praėjusį antradienį buvo atsisakyta, atsakymas yra užklausa, o ne spėjimas.

Vienintelis kirtimas: užregistruotas tik skaitymo leidimas

Kai vienas jūsų klientas atlieka darbą kitam, o pastarasis gali jį tikrinti, yra vienas sankcionuotas būdas pereiti ribą. Eilutes turinti organizacija įrašo leidimą. Skaitytojo organizacija įleidžia asmenį per vietą, turinčią teisę granted.read, kurioje never turi būti nurodyti owner ir admin. Skaitymas vykdomas kaip šeštasis duomenų bazės vaidmuo – skaitymo vieta, kuri gali atlikti atranką tik iš lentelių, išvardytų 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 pirmiausia įrašo peržiūrą paties skaitytojo nuomininke, tada susieja skaitymo vietą su leidimu, o šis įrašo peržiūrą turėtojo nuomininke. Pačios duomenų bazės politika patikrina, ar leidime nurodyta skaitytojo organizacija, ar jis apima lentelę, ar jis prasidėjo, nesibaigė ir nebuvo atšauktas, ir ar ši transakcija įrašė savo peržiūrą. Skaitymas, praleidžiantis peržiūrą, nieko nemato. Paleidimo metu assertSeatAtBoot(seatPool, schema) patikrina, ar iš seat.url atidarytas telkinys tikrai yra vieta ir nieko daugiau, o kitu atveju atmeta su DB_SEAT_ROLE_INVALID.

Išsiuntimas per UNO

Visi skaičiavimai vyksta per vieną klientą, sukurtą viename faile, su uždaru leidžiamųjų sąrašu:

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,
  });
}

Leidžiamųjų sąrašas sąmoningai yra modulio lygio konstanta. Jei operatorius galėtų jį išplėsti per konfigūraciją, maršrutas taptų viso registro išsiuntimo tarpine stotimi. Paties šablono testas patvirtina, kad sąraše nurodyti būtent tie užduočių tipai, į kuriuos kompiliuojamas manifestas.

Vokas

Išsiuntimo privalomąjį branduolį sudaro šeši laukai. Klientas nuomininką ir veikėją užpildo iš patikrintos apimties, niekada ne iš užklausos:

Laukas Kas jame saugoma
jobType Užduoties tipas su vardų sritimi, <plugin name>.<skill id>
organizationId Nuomininkas, iš apimties
userId Veikėjas, iš apimties, auditui ir atsiskaitymui
inputParams Įgūdžio įvestis. Joje niekada nėra nuomininko ID; įvestis, kurioje jis yra, atmetama išsiuntimo metu
priority critical, high, normal arba low
pluginId Jūsų manifesto name. Kiekvienas išsiuntimas deklaruoja savo kilmės įskiepį

Neprivalomi laukai apima correlationId (UUID (universaliai unikalų identifikatorių), arba sugeneruojamas naujas) ir callbackUrl, kurio reikia plugin_queue įgūdžiui, kad vykdyklė žinotų, kur išsiųsti rezultatą.

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, tada apklausa

Kiekvienas išsiuntimas įtraukiamas į eilę. Atsakymas visada yra 202 su identifikatoriais (jobId, runId, traceId, status), niekada ne rezultatas. Rezultatas gaunamas apklausiant užduotį arba per jūsų atgalinį iškvietimą. uno.peek(jobId, { scope }) jį nuskaito vieną kartą, o awaitJob apklausia iki galutinės būsenos; abi siunčia nuomininką iš patikrintos apimties ir abi jūsų tinklo kvietimo pusėje patikrina grąžintos eilutės organization_id pagal kviečiančiojo nuomininką, neatitikimą atmesdamos su SCOPE_REFUSED.

Vykdymo eilutę skaitykite jos pačios rašyba. Išsiuntimo atsakyme nurodyta jobId; eilutėje nurodyta job_id, organization_id ir plugin_id. Rezultato ir gedimo stulpeliai yra result, error, error_code ir error_troubleshooting. completed ir failed yra galutinės. timed_out, cancelled ir system_failure gaunamos iš valytuvo, ir vėlesnis rezultatas dar gali jas pataisyti. Klientas, laikantis bet kurią iš jų neapdorojama, atmeta eilutes, kurias platforma įrašo kasdien.

Patvirtinimo sulaikymas

Manifesto įgūdis, deklaruojantis approval, sulaikomas išsiuntimo metu. Tada 202 nurodo status: "awaiting_approval" ir turi waitpointId su manifeste nurodyta priežastimi. Vykdymas lieka sulaikytas, kol įvardytas asmuo dėl jo nusprendžia. uno.approve ir uno.resolveWaitpoint siunčia nuomininką ir kviečiantįjį kaip veikėją, o kito nei patikrintas kviečiantysis asmens sprendimas atmetamas. Patvirtinimas užduotį išleidžia vieną kartą ir dar kartą vykdo išsiuntimo patikras; atmetimas ją užbaigia failed. Antras sprendimas atmetamas, kaip ir sprendimas pasibaigus sulaikymo laikui. Jei jūsų produktui reikia, kad tvirtintojas būtų kitas asmuo nei siūlytojas, užtikrinkite tai maršrute, kuriame priimamas sprendimas: platforma fiksuoja abu.

Sulaikytą užduotį rodykite kaip sulaikytą. Nesakykite asmeniui, kad jo spustelėjimas ją išleido, kol to nenurodo vykdymo eilutė.

DI: pageidavimai įgūdžio eilutėje ir vienas nuskaitymas

Jūsų įskiepis niekada nekviečia modelio. Kai manifesto įgūdžiui jo reikia (llm_only arba tool_using, esant pasitikėjimo lygiui core arba verified), jūs nurodote pageidavimus jo registro eilutėje, o maršrutizatorius sprendžia iš pačios organizacijos telkinio:

{
  "execution_config_skill": {
    "preferredProvider": "gemini",
    "capabilityProfile": { "needsToolUse": true, "dataResidency": "eu_only" }
  }
}

preferredProvider ir preferredModel yra pageidavimai, kuriuos maršrutizatorius paiso tik tada, kai organizacijoje tas tiekėjas įjungtas ir jam pateikti prisijungimo duomenys. capabilityProfile filtruoja ir niekada nepasirenka; jo dataResidency (eu_only, us_only arba any) yra griežtas apribojimas, kurį maršrutizatorius įvykdo arba atsisako. Paprastai teisinga jų visų nenurodyti. modelOverride skirtas retam įgūdžiui, kuriam reikia vieno konkretaus modelio, ir jis šalia esančius pageidavimus padaro neveiksmingus; aš jo vengčiau, nebent įgūdis bet kuriame kitame modelyje neturi prasmės.

Kai jūsų sąsajai reikia parodyti, kurį modelį naudotų maršrutizatorius, nuskaitykite tai, o ne spėkite:

import { createAIRouteClient } from "@adverant-nexus/plugin-sdk/runtime/ai-route";

createAIRouteClient(...).effectiveRoute() yra vienintelis sankcionuotas DI tiekėjų maršrutizatoriaus nuskaitymas. Jis priima tinklų sietuvo adresą, paties kviečiančiojo nešėjo raktą ir jūsų platformos slug ir nesiunčia jokios DI užklausos. Jis atsako tiekėją ir modelį, politikos leidžiamus tiekėjus ir tai, ar pasirinktas galinis taškas veikia local, ar external. Kai maršrutu naudotis negalima, jis atsako maršrutizatoriaus atsisakymu žodžiais (NO_PROVIDER_FOR_ROLE, MODEL_CAPABILITY_UNAVAILABLE arba NO_MODEL_FOR_ROLE_AND_PROVIDER, su taisymo nurodymais), niekada ne numatytuoju modeliu. Parodykite tą atsisakymą asmeniui; tai kalba jo organizacijos konfigūracija.

Licencijų patikrinimai

Licencijavimą tikrina trys mechanizmai, trimis detalumo lygiais.

Teisė, kurioje nurodyta licencija. Paprasčiausias. Manifeste teisė turi licence: "<feature>", o apsauga, prieš nuskaitydama bet kurį vaidmenį, su paties kviečiančiojo prieigos raktu klausia tapatybės paslaugos, ar organizacijos licencija tai apima. Sukurkite apsaugą su skaitykle:

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 }) },
});

Licencija, kuri neapima funkcijos, atmeta visus su LICENCE_LOCKED, nurodydama, kas ją apima, ir pranešdama, kad organizacijos savininkai ir administratoriai gali ją įjungti. Licencija, kurios nepavyksta nuskaityti, atmeta su UNHANDLED_ERROR: užrakinta funkcija niekada neteikiama dėl to, kad licencija buvo nepasiekiama. Atsakymai įsimenami 30 sekundžių kiekvienai organizacijai ir funkcijai.

Produkto užtvara. createProductGate({ baseUrl, product }) iš runtime/product-gate klausia teisių patikros, ar kviečiančiojo organizacija apskritai turi jūsų produktą, o jos middleware() vykdoma po apimties apsaugos. Neigiamas sprendimas yra ENTITLEMENT_DENIED; nepasiekiama patikra yra ENTITLEMENT_UNREACHABLE, ir užtvara niekada nelaiko vieno kitu.

Pats licencijos dokumentas. Kodas, kuris turi pats nuspręsti pagal pasirašytą licenciją, pavyzdžiui, uždaras srities paketo modulis, naudoja verifyLicenceDocument(docText, opts) iš runtime/licence-document. Tai gryna funkcija: jokio tinklo kvietimo, jokio aplinkos kintamojo, jokio failo. Ji patikrina abu parašus pagal pasitikėjimo šaknis, kurias turi komponavimas, ir atsako būseną (VALID, WARN, GRACE, RESTRICT, TERMINATE arba ABSENT) su suteiktomis teisėmis, priedais ir srities paketais. Tada licenceAllows(verdict, featureGroup, action, tenantId?) nurodo, ar galite use arba provision grupėje. RESTRICT leidžia use ir atsako provision su LICENCE_LOCKED, todėl vykdomas darbas tęsiamas, o nieko naujo nepradedama.

Testavimas

Šablono testai parodo modelį; tai yra už jo esantys įrankiai.

Apimties imitacijos. Nustatytos apimties dublerį sukurkite vieną kartą, test/scope-fakes.ts, ir įterpkite jį visur, įskaitant nesančius atvejus: be padalinio, be prieigos rakto, prieigos raktas su nuline organizacija. Atsisakymo keliai ir yra produktas.

Imituotas išsiuntimo transportas. UnoClient priima fetch, now ir sleep, todėl vieneto testas niekada nesiekia tinklo. Patikrinkite voko laukus, 202 formą, apklausą iki galutinės eilutės su jos organization_id ir tai, kad kito nuomininko eilutė atmetama.

Tikras Postgres. Netikra užklausos funkcija patikrina tik SQL eilutę. Ji negali įrodyti, kad priverstinis eilučių lygio saugumas galioja arba kad failai taikomi eilės tvarka, kaip tai daro migratorius. testing/ephemeral-postgres paleidžia vienkartinį serverį ir vykdo tą patį nexus-migrate, kurį vykdo gamybinė aplinka:

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

Už CI (nuolatinės integracijos) ribų kompiuteris be Postgres serverio praleidžia kiekvieną duomenų bazės atvejį, nurodydamas jo pavadinimą ir sprendimo būdą, ir niekada nepažymi jo kaip sėkmingo. CI aplinkoje tas pats trūkumas lemia viso rinkinio nesėkmę (EPHEMERAL_POSTGRES_UNAVAILABLE_IN_CI), nes praleistas eilučių lygio saugumo testas yra sėkmingas patikros vartas, kuris nieko nepatikrino. Serveris paleidimo laukia iki 180 sekundžių, o stebėjimo procesas jį sustabdo, kai testo procesas baigiasi.

Izoliacijos testavimo priemonė. runIsolationHarness(target) iš testing/isolation-harness nuskaito kiekvieną jūsų programos prijungtą maršrutą ir atakuoja kiekvieną iš jų kaip kitos organizacijos administratorius ir kaip kolega. Tada ji atakuoja dar kartą pašalinus kodo užtvarą, duomenų bazės užtvarą ir abi. Maršrutas yra PROVEN tik tada, kai ataka nepavyksta esant bet kuriai užtvarai ir pasiekia aukos duomenis pašalinus abi, todėl žinote, kad testas apskritai gali aptikti nutekėjimą. Ji siunčia kiekvieno maršruto deklaruotą užklausą ir pavyzdinį turinį, todėl pasiekiamas net maršrutas, kuris atmeta tuščią užklausą. Užfiksuokite ledgerOf(report) teste ir laikykite testą nesėkmingu gavę defectsOf(report).

Registravimas: nuo manifesto iki įgūdžių registro

Jūsų manifesto įgūdžiai įgūdžių registrą pasiekia vienu keliu:

manifest.skills[]  →  compileRegistry(manifest)  →  POST /api/v1/plugins/sync

compileRegistry paverčia patvirtintą manifestą nexus.plugin-sync/v1 turiniu. Šablonas tai atlieka importavimo metu, todėl dėl netinkamo manifesto kūrimas nepavyksta:

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

Sinchronizavimas yra deklaratyvus: kiekvieną kartą siųskite visą įgūdžių rinkinį, o nepateiktas įgūdis išjungiamas, išsaugant jo istoriją. Jis yra griežtas: nežinomas laukas, kitos pakopos laukas arba null atmetami, visi pažeidimai grąžinami kartu viename 400 SYNC_CONTRACT_VIOLATION, ir kol yra bent vienas pažeidimas, niekas neįrašoma. Be to, jis įrašo po vieną registro eilutę kiekvienam įgūdžiui, kurios raktas yra vardų sritimi apibrėžtas užduoties tipas, su visais stulpeliais, kuriuos skaito dispečeris, todėl įgūdį galima vykdyti iškart, kai sinchronizavimas atsako 200.

Įskiepis yra autentifikuotas iškvietėjas, o ne turinio laukas. Iškvieskite sinchronizavimą iš savo įskiepio darbo krūvio per mTLS (abipusį TLS: Transport Layer Security su sertifikatu abiejuose galuose). Skills Engine nuskaito jūsų darbo krūvio kliento sertifikatą, kurio SPIFFE tapatybė (spiffe://<trust-domain>/ns/<namespace>/sa/<service-account>) nurodo vardų sritį ir paslaugos paskyrą, ir suranda tai vardų sričiai užregistruotą įskiepį bei jam priklausančią organizaciją. Turinio pluginId turi sutapti; tai patikra, o ne parinkiklis. Kiekviena eilutė įrašoma su tuo įskiepiu ir organizacija.

Būsena Kodas Reikšmė
200 {contract, pluginId, version, created, updated, unchanged, disabled, skills}
400 SYNC_CONTRACT_VIOLATION Kiekvienas pažeidimas nurodytas violations[]; niekas neįrašyta
401 UNAUTHORIZED Netinkamas arba trūkstamas paslaugos raktas
401 CALLER_IDENTITY_UNVERIFIED Nėra nuskaitomos kliento tapatybės
403 DELIVERY_IDENTITY_MISSING Kviečiančioji vardų sritis nepriklauso jokiam įskiepiui
403 PLUGIN_ID_MISMATCH Turinyje nurodytas kitas įskiepis
409 REGISTRY_CONFLICT Užduoties tipas priklauso kitam savininkui arba buvo užregistruotas ne per sinchronizavimą; niekas neįrašyta

Laikykite diegimo veiksmą nesėkmingu esant bet kokiai kitai būsenai nei 200. Jokia kita būsena nereiškia, kad jūsų įgūdžiai užregistruoti.

Įvedimas

Įtraukimas vykdomas dešimčia nuoseklių veiksmų, kurių kiekvieną galima atskirai paleisti iš naujo, atšaukti arba atkurti į ankstesnę būseną:

  1. Klonuokite saugyklą ir ją patvirtinkite.
  2. Išanalizuokite manifestą.
  3. Patikrinkite, ar nėra saugumo problemų.
  4. Sukurkite atvaizdą.
  5. Nusiųskite jį į įdiegimo registrą.
  6. Nustatykite jo domenų vardus.
  7. Įdiekite jį per įdiegimo leidimų kanalus.
  8. Palaukite būklės patikros.
  9. Užregistruokite įskiepį.
  10. Informuokite kūrėją.

Prieš diegimą su manifestu ir sukurtu atvaizdu atliekamos penkios atitikties patikros: manifestas išanalizuojamas ir turi privalomus laukus; kiekvienas deklaruotas maršrutas yra tikras užregistruotas maršrutas; įskiepiui priklauso jo schema ir jis nieko nerašo už jos ribų; išteklių užklausos deklaruotos ir neviršija ribų; atvaizdas turi veikiančią būklės tvarkyklę. Įskiepis, kuris užsiregistruoja paleidimo metu, vykdo tą pačią sutartį savo paties įgaliojimais, todėl patikros tampa jo CI, o ne konvejerio. Praleidus vieną iš jų, įtraukimas netrumpėja; nesėkmė tik perkeliama į vykdymo laiką.

Jūsų manifeste nurodytas prekės ženklo apipavidalinimas pateikiamas pagal domeną be autentifikavimo, nes prisijungimo puslapiui jo reikia dar prieš tai, kai kas nors turi kredencialus. Viską, kas yra branding, laikykite viešu.

Aplinkos ir perkėlimas
Aplinkos ir perkėlimas
Aplinkos ir perkėlimas perkelia kiekvieną leidimą iš kūrimo erdvės per bandomąją aplinką į pilotinį padalinį, o tada į visus padalinius, rodydamas kiekvieną patikros vartą ir jo būseną viename puslapyje. Perkėlimas, praleidžiantis patikros vartą, atmetamas su GATE_CANNOT_BE_SKIPPED.
Kanalai ir įdiegimai
Kanalai ir diegimai
Kanalai ir įdiegimai rodo, kuris padalinys vykdo kurią versiją, o klaidų dažnis pateikiamas kaip skaičiai, niekada ne kaip turinys. Vieno padalinio atkūrimas į ankstesnę versiją yra peržiūrimas pakeitimas, paveikiantis tik tą padalinį.

Ko vykdymo aplinka už jus nepadarys

Vykdymo aplinka užtikrina izoliaciją, paskirstymą ir prieigą prie modelių. Ji nepadarys jūsų produkto logikos teisingos ir nepagreitins lėtos užklausos: kiekvienas sakinys vykdomas susietoje transakcijoje su skirtaisiais laikais, kuriuos deklaruoja jūsų manifesto db blokas, o sakinys, viršijantis statementTimeoutMs, atšaukiamas, o ne laukiamas. Pritaikykite savo užklausas prie to. Be to, patvirtinimo sulaikymas, skaitymo vieta ir licencijos skaitytuvas kiekvienas prideda vieną kreipinį arba transakciją. Mano anomalijų peržiūros įskiepyje licencijos patikra pridėdavo kelias milisekundes kiekvienai užklausai, kol neužsipildė jos 30 sekundžių atmintis, ir tai buvo teisinga kaina už tai, kad niekada nebuvo pateikta užrakinta funkcija.