IdħolIbbukkja laqgħa informattiva

Kapitlu 2.22

Ir-runtime tal-plugin

Il-moduli tal-SDK (software development kit) li fuqhom jaħdem il-plugin tiegħek, mill-għassa tal-iskop u l-ilqugħ tad-database sa UNO dispatch, il-qari tar-rotta tal-IA (intelliġenza artifiċjali) u l-kontrolli tal-liċenzja. Imbagħad l-ittestjar ma' database reali, ir-reġistrazzjoni tal-ħiliet tiegħek u l-onboarding.

Din il-paġna ġiet tradotta bl-IA mill-oriġinal bl-Ingliż. Jekk xi ħaġa mhijiex ċara, il-paġna bl-Ingliż hija r-referenza. Aqra din il-paġna bl-Ingliż

21 minuti qari

In-nofs tar-runtime tal-SDK (kit għall-iżvilupp tas-softwer) huwa sett ta' moduli taħt @adverant-nexus/plugin-sdk/runtime/*, flimkien ma' għodod ta' għajnuna għat-testijiet taħt testing/*. Intom timportawhom; ma terġgħux timplimentawhom. Dik hija l-idea kollha, u ħadtli reviżjoni waħda miċħuda biex nieħu din bis-serjetà: in-nota tar-reviżur dwar il-kontroll tal-ambitu miktub bl-idejn fl-ewwel plugin tiegħi kienet linja waħda, "l-SDK diġà għandu dan, u tiegħek jaċċetta token ta' sfida MFA (awtentikazzjoni b'diversi fatturi) bħala sessjoni".

Dan il-kapitlu jsegwi talba permezz ta' plugin li qed jaħdem, kif jgħaqqadha t-template full-service: il-gwardja tal-ambitu, iċ-ċint tad-database, il-qsim wieħed permess, id-dispaċċ permezz tal-UNO, il-qari tar-rotta tal-IA (intelliġenza artifiċjali) u l-kontrolli tal-liċenzja. Imbagħad ikopri l-ittestjar, ir-reġistrazzjoni tal-ħiliet tal-manifest tagħkom, u l-passi tal-onboarding.

Skop: għassa waħda għal kull framework

Kull rotta /api għandha l-gwardja tal-ambitu. Hija tivverifika t-token bearer, issolvi t-tliet assi (tenant, sid, unità) minnu, tirrifjuta korp li jsemmi tenant, tapplika d-dritt tar-rotta mir-reġistru tal-manifest, u biss imbagħad tħalli lill-handler jaħdem. L-SDK jinkludi adapter wieħed għal kull framework, kollha minn @adverant-nexus/plugin-sdk/runtime/scope u kollha jieħdu l-istess għażliet.

Framework Adapter
Express scopeMiddleware
Fastify requireScope, bħala preHandler
Li jmiss withScope, li jgeżwer il-handler; handler ta' Next ma jiġix mgħarraf bir-rotta tiegħu, għalhekk withScope jeħodha bħala t-tielet argument

Hawn hu l-wiring Express tat-template, imqassar. Il-verifikatur huwa dak tal-SDK, u jżomm it-token fil-format tas-sessjoni tas-servizz tal-identità: HS256 biss; iss, exp, iat u jti meħtieġa; ħajja ta' mhux aktar minn siegħa; u l-ebda sfida MFA, impersonazzjoni jew token ta' riżorsa OAuth (l-istandard miftuħ għall-awtorizzazzjoni delegata) ma huma ammessi bħala sessjoni.

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

Il-gwardja tad-drittijiet tapplika d-dritt ta' rotta f'erba' passi. Rwol fil-lista never tad-dritt jirrifjuta b'AUTHORITY_EXCEEDED u bil-kliem barred, u l-ebda post ma jneħħi dan. Rwol f'roles jammetti, flimkien ma' post attiv meta d-dritt jgħid seat: true. Inkella post attiv li jġorr id-dritt jammetti. Inkella t-talba tiġi rrifjutata AUTHORITY_EXCEEDED, u jissemmew in-nies li jistgħu jagħtu post. Agħtu lill-gwardja store (rights: { manifest, store: { pool, schema } }) u din taqra l-postijiet taħt l-ambitu proprju ta' min qed isejjaħ; dritt li jsemmi licence jeħtieġ ukoll qarrej tal-liċenzji, kif spjegat hawn taħt.

Ġewwa handler, scopeOf(req) huwa l-uniku mod kif jinqara l-ambitu solvut, u jitfa' eċċezzjoni jekk il-gwardja ma ħadmitx. Gwardja rreġistrata fuq prefiss, li taħdem qabel ma tkun tqabblet xi rotta, twieġeb 500 MIDDLEWARE_ORDERING_ERROR; rotta li l-kodiċi tagħkom jirreġistra u li l-manifest ma jiddikjarax twieġeb 500 UNHANDLED_ERROR. It-tnejn ifallu magħluqa.

Ir-rotot /internal tat-template, li l-pjattaforma ssejjaħ, jużaw ir-reġim l-ieħor. Il-gwardja tas-servizz tiċċekkja X-Service-Key f'ħin kostanti u tieħu t-tenant minn X-Organization-ID tal-pjattaforma, filwaqt li tirrifjuta MISSING_SERVICE_KEY, INVALID_SERVICE_KEY jew MISSING_ORG_ID_HEADER. Għat-token iffirmat tal-pjattaforma għal kull sejħa, l-SDK għandu requireService (Fastify) u serviceMiddleware (Express), li jiċċekkjaw ukoll għal liema ħila u rotta nħareġ it-token u jirrifjutaw token użat darbtejn.

Iċ-ċint tad-database: tenantFence u withScopedTx

Kull struzzjoni kontra tabella b'ambitu tibni ċ-ċint u taħdem ġewwa tranżazzjoni b'ambitu:

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) jibni l-predikat u l-parametri tiegħu minn ambitu solvut. Għaddu owner għat-tabelli personali; ħalluh barra għall-artefatti tal-organizzazzjoni fejn is-sid huwa provenjenza. Meta l-istruzzjoni diġà għandha parametri, startIndex jgħid liċ-ċint minn fejn għandu jibda jnumera. Insert qatt ma jieħu l-assi bħala input: jikteb scope.tenant, scope.owner u scope.unit mill-ambitu.

withScopedTx jorbot it-tliet assi għal tranżazzjoni waħda permezz tal-funzjoni unika ta' rabta tal-iskema, imbagħad iħaddem il-callback tagħkom. It-tieni rabta fl-istess tranżazzjoni tqajjem SCOPE_ALREADY_BOUND (500: il-kodiċi tagħkom rabat darbtejn; min sejjaħ ma għamel xejn ħażin). Tenant jew sid nieqes jew żero jqajjem SCOPE_PREDICATE_INVALID (403). L-issettjar huwa lokali għat-tranżazzjoni, għalhekk konnessjoni mill-pool ma tistax iġġorr tenant wieħed fit-talba ta' wara.

Żewġ funzjonijiet relatati jkopru l-każijiet li mhumiex talba ta' persuna. withTenantScopedTx jorbot it-tenant u l-unità mingħajr sid, għal ringieli li jaqrahom magna (ir-reġistru tal-apparati), u jirrifjuta ambitu li jġorr sid. maintenanceScope(reason) iġiegħel operazzjoni fuq l-organizzazzjoni kollha tiddikjara b'mod espliċitu x'inhi qabel ma tinfetaħ it-tranżazzjoni tas-sid. Iċ-ċint fil-kodiċi u s-sigurtà sfurzata fil-livell tar-ringiela huma żewġ mekkaniżmi għal liġi waħda; il-kontroll tal-boot jirrifjuta li jisma' sakemm id-database ma turix li t-tieni wieħed jgħodd (DB_ROLE_BYPASSES_ISOLATION inkella).

Kull rifjut huwa ringiela

It-template jinstalla biċċa middleware oħra, darba waħda, bejn il-body parser u r-routers: ir-reġistru tar-rifjuti.

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

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

Jgeżwer ir-rispons b'mod li kull rifjut li persuna taqra, kemm jekk mill-gwardja tad-drittijiet, minn handler jew minn store, jinkiteb fit-tabella refusal tal-iskema tagħkom ġewwa t-tranżazzjoni b'ambitu ta' dik il-persuna stess qabel ma jintbagħat il-korp. 401 anonimu ma jikteb xejn. Jekk ir-ringiela ma tistax tinkiteb, it-tweġiba ssir UNHANDLED_ERROR: "le" li l-prodott ma jistax jirreġistra ma jintbagħatx daqslikieku ġie rreġistrat. Il-boot iħaddem assertRefusalLedger biex jiċċekkja li t-tabella tista' tieħu r-ringiela tar-reġistru, u store jista' jsejjaħ noteSubject({ recordId, isDemo }) sabiex kull rifjut isemmi r-rekord li kien dwaru. Meta klijent jistaqsi għaliex xi ħadd ġie miċħud nhar it-Tlieta li għadda, it-tweġiba hija query, mhux suppożizzjoni.

L-uniku qsim: għotja rreġistrata li tinqara biss

Meta wieħed mill-klijenti tagħkom jagħmel xogħol għal ieħor u l-ieħor jista' jispezzjonah, hemm mod approvat wieħed biex jinqasam il-konfini. L-organizzazzjoni li żżomm ir-ringieli tirreġistra għotja. L-organizzazzjoni tal-qarrej tammetti persuna permezz ta' post li jġorr id-dritt granted.read, li għandu jsemmi owner u admin f'never. Il-qari jsir bħala s-sitt rwol tad-database, il-post tal-qari, li jista' jagħżel biss it-tabelli li jelenka 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 l-ewwel jikteb il-ħarsa fit-tenant proprju tal-qarrej, imbagħad jorbot il-post tal-qari mal-għotja, li tikteb il-ħarsa fit-tenant ta' min iżomm ir-ringieli. Il-politika tad-database stess tiċċekkja li l-għotja ssemmi l-organizzazzjoni tal-qarrej, tkopri t-tabella, bdiet, għadha ma ntemmitx u ma ġietx irtirata, u li din it-tranżazzjoni kitbet il-ħarsa tagħha. Qari li jaqbeż il-ħarsa ma jara xejn. Mal-boot, assertSeatAtBoot(seatPool, schema) jiċċekkja li l-pool miftuħ minn seat.url huwa tassew il-post u xejn aktar, u inkella jirrifjuta b'DB_SEAT_ROLE_INVALID.

Dispatch permezz ta' UNO

Il-komputazzjoni kollha tgħaddi minn klijent wieħed, mibni f'fajl wieħed, b'lista magħluqa ta' dak li hu permess:

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

Il-lista ta' dak li hu permess hija kostanti fil-livell tal-modulu apposta. Kieku operatur seta' jwessagħha mill-konfigurazzjoni, ir-rotta kienet issir proxy tad-dispaċċ għar-reġistru kollu. It-test tat-template stess jasserixxi li l-lista ssemmi eżattament it-tipi ta' xogħol li l-manifest jikkompila għalihom.

L-envelopp

Dispaċċ iġorr sitt oqsma fil-qalba meħtieġa tiegħu. Il-klijent jimla t-tenant u l-attur mill-ambitu vverifikat, qatt mit-talba:

Qasam X'fih
jobType It-tip ta' xogħol b'namespace, <plugin name>.<skill id>
organizationId It-tenant, mill-ambitu
userId L-attur, mill-ambitu, għall-awditjar u l-ħlas
inputParams L-input tal-ħila. Qatt ma jġorr id tat-tenant; input li jġorr wieħed jiġi rrifjutat fid-dispaċċ
priority critical, high, normal jew low
pluginId Il-name tal-manifest tagħkom. Kull dispaċċ jiddikjara l-plugin minn fejn joriġina

Oqsma fakultattivi jinkludu correlationId (UUID (identifikatur universalment uniku), jew jinħoloq wieħed ġdid) u callbackUrl, li ħila plugin_queue teħtieġ biex il-worker ikun jaf fejn għandu jibgħat ir-riżultat tiegħu.

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, imbagħad polling

Kull dispaċċ jitpoġġa fil-kju. It-tweġiba hija dejjem 202 b'identifikaturi (jobId, runId, traceId, status), qatt riżultat. Ir-riżultat jiġi mill-polling tax-xogħol jew mill-callback tagħkom. uno.peek(jobId, { scope }) jaqrah darba u awaitJob jagħmel polling sa status terminali; it-tnejn jibagħtu t-tenant mill-ambitu vverifikat, u t-tnejn jiċċekkjaw organization_id tar-ringiela rritornata mat-tenant ta' min qed isejjaħ min-naħa tagħkom tas-sejħa tan-netwerk, u jirrifjutaw nuqqas ta' qbil b'SCOPE_REFUSED.

Aqraw ir-ringiela tal-eżekuzzjoni bl-ortografija tagħha stess. Ir-rispons tad-dispaċċ jgħid jobId; ir-ringiela tgħid job_id, organization_id u plugin_id. Il-kolonni tar-riżultat u tal-falliment huma result, error, error_code u error_troubleshooting. completed u failed huma terminali. timed_out, cancelled u system_failure jiġu mir-reaper u riżultat tard xorta jista' jikkoreġihom. Klijent li jittratta kwalunkwe minn dawn bħala mhux interpretabbli jirrifjuta ringieli li l-pjattaforma tikteb kuljum.

Iż-żamma għall-approvazzjoni

Ħila tal-manifest li tiddikjara approval tinżamm fid-dispaċċ. 202 imbagħad jgħid status: "awaiting_approval" u jġorr waitpointId, bir-raġuni li ta l-manifest. L-eżekuzzjoni tibqa' miżmuma sakemm persuna msemmija tiddeċiedi dwarha. uno.approve u uno.resolveWaitpoint jibagħtu t-tenant u lil min qed isejjaħ bħala l-attur, u deċiżjoni minn xi ħadd li mhuwiex min qed isejjaħ ivverifikat tiġi rrifjutata. Approvazzjoni teħles ix-xogħol darba u terġa' tħaddem il-kontrolli tad-dispaċċ; rifjut itemmu failed. It-tieni deċiżjoni tiġi rrifjutata, u hekk ukoll deċiżjoni wara li tiskadi ż-żamma. Jekk il-prodott tagħkom jeħtieġ li min japprova jkun persuna differenti minn min jipproponi, infurzaw dan fir-rotta li tiddeċiedi: il-pjattaforma tirreġistra lit-tnejn.

Uru xogħol miżmum bħala miżmum. Tgħidux lil persuna li l-klikk tagħha ħeles l-eżekuzzjoni sakemm ir-ringiela tal-eżekuzzjoni ma tgħidx hekk.

IA: xewqat fuq ir-ringiela tal-ħiliet, u qari wieħed

Il-plugin tagħkom qatt ma jsejjaħ mudell. Meta ħila tal-manifest teħtieġ wieħed (llm_only jew tool_using, b'livell ta' fiduċja core jew verified), tesprimu preferenzi fuq ir-ringiela tagħha fir-reġistru, u r-router jiddeċiedi mill-pool proprju tal-organizzazzjoni:

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

preferredProvider u preferredModel huma xewqat li r-router jonora biss meta l-organizzazzjoni jkollha dak il-fornitur attivat u bil-kredenzjali. capabilityProfile jiffiltra u qatt ma jagħżel; il-dataResidency tiegħu (eu_only, us_only jew any) huwa restrizzjoni assoluta li r-router jew jissodisfa jew jirrifjuta. Li tħallu barra lil kollha ġeneralment huwa l-għażla t-tajba. modelOverride jeżisti għall-ħila rari li teħtieġ mudell eżatt wieħed, u jagħmel ix-xewqat ta' ħdejh inerti; jien nevitah sakemm il-ħila ma tkunx bla sens fuq kwalunkwe mudell ieħor.

Meta l-interfaċċja tagħkom teħtieġ turi liema mudell kien juża r-router, aqrawh, tbassruhx:

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

createAIRouteClient(...).effectiveRoute() huwa l-uniku qari approvat tal-AI Provider Router. Jieħu l-indirizz tal-gateway, il-bearer proprju ta' min qed isejjaħ u s-slug tal-pjattaforma tagħkom, u ma jibgħat l-ebda talba lill-IA. Iwieġeb il-fornitur u l-mudell, il-fornituri li l-politika tippermetti, u jekk l-endpoint magħżul iħaddimx local jew external. Meta r-rotta ma tkunx użabbli jwieġeb ir-rifjut tar-router bil-kliem (NO_PROVIDER_FOR_ROLE, MODEL_CAPABILITY_UNAVAILABLE jew NO_MODEL_FOR_ROLE_AND_PROVIDER, bir-rimedju), qatt mudell default. Uru dak ir-rifjut lill-persuna; hija l-konfigurazzjoni tal-organizzazzjoni tagħha li qed titkellem.

Kontrolli tal-liċenzja

Tliet mekkaniżmi jiċċekkjaw il-liċenzjar, fi tliet livelli ta' granularità.

Dritt li jsemmi liċenzja. L-aktar sempliċi. Fil-manifest, dritt iġorr licence: "<feature>", u l-gwardja tistaqsi lis-servizz tal-identità jekk il-liċenzja tal-organizzazzjoni ġġorrx dan, bit-token proprju ta' min qed isejjaħ, qabel ma jinqara kwalunkwe rwol. Ibnu l-gwardja b'qarrej:

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

Liċenzja li ma ġġorrx il-funzjoni tirrifjuta lil kulħadd b'LICENCE_LOCKED, issemmi x'iġorrha u tgħid li s-sidien u l-amministraturi tal-organizzazzjoni jistgħu jixgħeluha. Liċenzja li ma tistax tinqara tirrifjuta UNHANDLED_ERROR: funzjoni msakkra qatt ma tiġi servuta minħabba li l-liċenzja ma kinitx tintlaħaq. It-tweġibiet jinżammu fil-memorja għal 30 sekonda għal kull organizzazzjoni u funzjoni.

Il-bieb tal-prodott. createProductGate({ baseUrl, product }) minn runtime/product-gate jistaqsi lill-kontroll tal-intitolament jekk l-organizzazzjoni ta' min qed isejjaħ għandhiex il-prodott tagħkom fl-ewwel lok, u l-middleware() tiegħu jaħdem wara l-gwardja tal-ambitu. Verdett negattiv huwa ENTITLEMENT_DENIED; kontroll li ma jistax jintlaħaq huwa ENTITLEMENT_UNREACHABLE, u l-bieb qatt ma jittratta wieħed bħala l-ieħor.

Id-dokument tal-liċenzja nnifsu. Kodiċi li għandu jiddeċiedi waħdu mil-liċenzja ffirmata, bħall-modulu magħluq ta' domain pack, juża verifyLicenceDocument(docText, opts) minn runtime/licence-document. Hija funzjoni pura: l-ebda sejħa tan-netwerk, l-ebda varjabbli tal-ambjent, l-ebda fajl. Tiċċekkja ż-żewġ firem kontra l-għeruq tal-fiduċja li jġorr il-build u twieġeb stat (VALID, WARN, GRACE, RESTRICT, TERMINATE jew ABSENT) bl-għotjiet, l-add-ons u d-domain packs. licenceAllows(verdict, featureGroup, action, tenantId?) imbagħad jgħid jekk tistgħux use jew provision taħt grupp. RESTRICT jippermetti use u jwieġeb provision b'LICENCE_LOCKED, għalhekk ix-xogħol li qed jaħdem ikompli u xejn ġdid ma jibda.

Ittestjar

It-testijiet tat-template juru x-xejra; dawn huma l-għodod warajha.

Imitazzjonijiet tal-ambitu. Ibnu d-doppju tal-ambitu solvut darba, f'test/scope-fakes.ts, u injettawh kullimkien, inklużi l-każijiet nieqsa: l-ebda unità, l-ebda token, token b'organizzazzjoni żero. Il-mogħdijiet tar-rifjut huma l-prodott.

Trasport tad-dispaċċ falz. UnoClient jieħu fetch, now u sleep, għalhekk test tal-unità qatt ma jmiss in-netwerk. Assertaw l-oqsma tal-envelopp, il-forma 202, il-polling sa ringiela terminali bil-organization_id tagħha, u li ringiela għal tenant ieħor titwarrab.

Postgres reali. Funzjoni ta' query falza tipprova biss string tal-SQL. Ma tistax tipprova li s-sigurtà obbligatorja fil-livell tar-ringiela żżomm, jew li l-fajls jiġu applikati fl-ordni bħalma jagħmel il-migrator. testing/ephemeral-postgres jibda server temporanju u jħaddem l-istess nexus-migrate li tħaddem il-produzzjoni:

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

Barra mis-CI (integrazzjoni kontinwa), magna mingħajr server Postgres taqbeż kull każ tad-database bl-isem tiegħu u bir-rimedju, u qatt ma tgħaddih bħala aħdar. Fis-CI l-istess nuqqas ifalli s-suite (EPHEMERAL_POSTGRES_UNAVAILABLE_IN_CI), għax test tas-sigurtà fil-livell tar-ringiela li jinqabeż huwa grada ħadra li ma kejlet xejn. Is-server jistenna sa 180 sekonda biex jibda, u watchdog iwaqqfu meta l-proċess tat-test jispiċċa.

Il-harness tal-iżolament. runIsolationHarness(target) minn testing/isolation-harness jaqra kull rotta li l-app tiegħek timmonta u jattakka kull waħda bħala l-amministratur ta' organizzazzjoni oħra u bħala kollega. Imbagħad jerġa' jattakka bl-ilqugħ tal-kodiċi mneħħi, bl-ilqugħ tad-database mneħħi, u biż-żewġ. Rotta hija PROVEN biss meta l-attakk ifalli b'xi wieħed miż-żewġ ilqugħ f'postu u jilħaq id-data tal-vittma meta t-tnejn jitneħħew, sabiex tkun taf li t-test ikun jista' jara tnixxija. Jibgħat il-query dikjarata u l-body ta' eżempju ta' kull rotta, sabiex rotta li tirrifjuta talba vojta xorta tintlaħaq. Waħħal ledgerOf(report) f'test u falli fuq defectsOf(report).

Reġistrazzjoni: mill-manifest għar-reġistru tal-ħiliet

Il-ħiliet tal-manifest tiegħek jilħqu r-reġistru tal-ħiliet permezz ta' triq waħda:

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

compileRegistry jibdel manifest ivvalidat fil-body ta' nexus.plugin-sync/v1. Il-mudell jagħmel dan fl-importazzjoni, sabiex manifest invalidu jfalli l-build:

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

Is-sync huwa dikjarattiv: ibgħat is-sett sħiħ tal-ħiliet kull darba, u ħila li titħalla barra tiġi diżattivata, bl-istorja tagħha tinżamm. Huwa strett: qasam mhux magħruf, qasam ta' livell ieħor jew null jiġi rrifjutat, il-ksur kollu jiġi lura flimkien f'400 SYNC_CONTRACT_VIOLATION wieħed, u xejn ma jinkiteb sakemm ikun hemm ksur wieħed. U jikteb ringiela waħda fir-reġistru għal kull ħila, biċ-ċavetta tkun it-tip ta' xogħol bin-namespace, li jkollha kull kolonna li jaqra d-dispatcher, sabiex il-ħila tkun tista' titħaddem hekk kif is-sync iwieġeb 200.

Il-plugin huwa l-chiamant awtentikat, qatt mhux qasam fil-body. Sejjaħ is-sync mill-workload tal-plugin tiegħek stess fuq mTLS (TLS reċiproku: Transport Layer Security b'ċertifikat fiż-żewġ naħat). Is-Skills Engine jaqra ċ-ċertifikat tal-klijent tal-workload tiegħek, li l-identità SPIFFE tiegħu (spiffe://<trust-domain>/ns/<namespace>/sa/<service-account>) issemmi n-namespace u s-service account, u jfittex il-plugin u l-organizzazzjoni sid irreġistrati għal dak in-namespace. Il-pluginId tal-body irid jaqbel; huwa verifika, mhux selettur. Kull ringiela tinkiteb b'dak il-plugin u b'dik l-organizzazzjoni.

Stat Kodiċi Tifsira
200 {contract, pluginId, version, created, updated, unchanged, disabled, skills}
400 SYNC_CONTRACT_VIOLATION Kull ksur elenkat f'violations[]; xejn ma jinkiteb
401 UNAUTHORIZED Service key ħażina jew nieqsa
401 CALLER_IDENTITY_UNVERIFIED L-ebda identità tal-klijent li tista' tinqara
403 DELIVERY_IDENTITY_MISSING In-namespace li qed isejjaħ ma jappartjeni għall-ebda plugin
403 PLUGIN_ID_MISMATCH Il-body isemmi plugin ieħor
409 REGISTRY_CONFLICT Tip ta' xogħol huwa proprjetà ta' xi ħadd ieħor jew ġie rreġistrat barra mis-sync; xejn ma jinkiteb

Falli l-pass tad-deploy tiegħek fuq kull status ħlief 200. L-ebda status ieħor ma jfisser li l-ħiliet tiegħek huma rreġistrati.

Onboarding

L-onboarding jitħaddem f'għaxar passi ordnati, li kull wieħed minnhom jista' jerġa' jitħaddem, jiġi kkanċellat jew jitreġġa' lura waħdu:

  1. Ikkloonja r-repożitorju u vvalidah.
  2. Analizza l-manifest.
  3. Skennjah għal problemi ta' sigurtà.
  4. Ibni l-immaġni.
  5. Ibgħatha fir-reġistru tal-installazzjoni.
  6. Issettja l-ismijiet tad-dominju tagħha.
  7. Iddeployjaha, permezz tal-kanali tar-rilaxx tal-installazzjoni.
  8. Stenna l-verifika tas-saħħa.
  9. Irreġistra l-plugin.
  10. Għarraf lill-iżviluppatur.

Qabel id-deploy, jitħaddmu ħames verifiki ta' konformità fuq il-manifest u l-immaġni mibnija: il-manifest jiġi analizzat u fih l-oqsma meħtieġa; kull rotta dikjarata hija rotta reali rreġistrata; il-plugin huwa sid l-iskema tiegħu u ma jikteb xejn barra minnha; it-talbiet tar-riżorsi huma dikjarati u fil-limiti; u l-immaġni għandha handler tas-saħħa li jaħdem. Plugin li jirreġistra lilu nnifsu fil-boot iħaddem l-istess kuntratt taħt l-awtorità tiegħu stess, sabiex il-verifiki jsiru s-CI tiegħu minflok dak tal-pipeline. Jekk taqbeż waħda, l-onboarding ma jqassarx; il-falliment sempliċement jiċċaqlaq għar-runtime.

Il-branding fil-manifest tiegħek jiġi servut mingħajr awtentikazzjoni skont id-dominju, għax il-paġna tad-dħul teħtieġu qabel ma xi ħadd ikollu kredenzjali. Ittratta kull ma hemm f'branding bħala pubbliku.

Ambjenti u promozzjoni
Ambjenti u promozzjoni
Ambjenti u promozzjoni jmexxi kull rilaxx mill-ispazju tal-iżvilupp għal staging, imbagħad għal unità pilota, u mbagħad għall-unitajiet kollha, b'kull grada u l-istat tagħha f'paġna waħda. Promozzjoni li taqbeż grada tiġi rrifjutata b'GATE_CANNOT_BE_SKIPPED.
Kanali u installazzjonijiet
Kanali u installazzjonijiet
Kanali u installazzjonijiet juri liema unità tħaddem liema verżjoni, bir-rati tal-iżbalji bħala għadd u qatt bħala kontenut. It-treġġigħ lura ta' unità waħda huwa bidla riveduta li tolqot dik l-unità biss.

Dak li r-runtime mhux se jagħmel għalik

Ir-runtime iżomm sod fuq l-iżolament, id-dispatch u l-aċċess għall-mudelli. Ma jagħmilx il-loġika tal-prodott tiegħek korretta, u ma jagħmilx query bil-mod mgħaġġla: kull statement jitħaddem ġewwa tranżazzjoni marbuta bit-timeouts li jiddikjara l-blokk db tal-manifest tiegħek, u statement li jaqbeż statementTimeoutMs jiġi kkanċellat, mhux mistenni. Iddisinja l-queries tiegħek għal dan. U ż-żamma għall-approvazzjoni, is-seat tal-qari u l-qarrej tal-liċenzja kollha jżidu round trip jew tranżazzjoni. Fil-plugin tiegħi għar-reviżjoni tal-anomaliji, il-verifika tal-liċenzja żiedet ftit millisekondi għal kull talba sakemm il-memorja tagħha ta' 30 sekonda saħnet, li kien prezz ġust biex qatt ma tiġi servuta funzjoni msakkra.