Oturum açınToplantı planlayın

Bölüm 2.22

Eklenti çalışma zamanı (runtime)

Kapsam korumasından ve veritabanı çitinden UNO dağıtımına (dispatch), YZ (yapay zeka) rota okumasına ve lisans kontrollerine kadar eklentinizin üzerinde çalıştığı SDK (yazılım geliştirme kiti) modülleri. Ardından gerçek bir veritabanına karşı test etme, becerilerinizi kaydetme ve ilk kullanıma hazırlama (onboarding).

Bu sayfa, İngilizce aslından YZ tarafından çevrilmiştir. Anlaşılmayan bir yer olursa İngilizce sayfa esas alınır. Bu sayfayı İngilizce okuyun

21 dakikalık okuma

SDK'nın (yazılım geliştirme kiti) çalışma zamanı yarısı, @adverant-nexus/plugin-sdk/runtime/* altındaki bir dizi modülden ve testing/* altındaki test yardımcılarından oluşur. Bunları içe aktarırsınız; yeniden uygulamazsınız. Tüm fikir budur ve bunu ciddiye almam için bir incelemenin reddedilmesi gerekti: ilk eklentimin elle yazılmış kapsam kontrolüne inceleyicinin düştüğü not tek bir satırdı: "SDK'da bu zaten var ve sizinki bir MFA (çok faktörlü kimlik doğrulama) doğrulama belirtecini oturum olarak kabul ediyor".

Bu bölüm, tam hizmet şablonunun bağladığı şekliyle, çalışan bir eklenti üzerinden geçen bir isteği takip eder: kapsam koruması, veritabanı sınırı, izin verilen tek geçiş, UNO üzerinden gönderim, YZ (yapay zeka) rotası okuması ve lisans kontrolleri. Ardından test etmeyi, bildirim becerilerinizi kaydetmeyi ve devreye alma adımlarını ele alır.

Kapsam: çerçeve (framework) başına bir koruma

Her /api rotası kapsam korumasını taşır. Hamil (bearer) belirtecini doğrular, bundan üç ekseni (kiracı, sahip, birim) çözümler, bir kiracı adı veren gövdeyi reddeder, bildirimin kaydından rotanın hakkını uygular ve yalnızca o zaman işleyicinin çalışmasına izin verir. SDK, tümü @adverant-nexus/plugin-sdk/runtime/scope içinden gelen ve tümü aynı seçenekleri alan, çerçeve başına bir bağdaştırıcı sunar.

Çerçeve Bağdaştırıcı
Express scopeMiddleware
Fastify requireScope, bir preHandler olarak
Next withScope, işleyiciyi sarmalar; bir Next işleyicisine rotası bildirilmez, bu nedenle withScope bunu üçüncü bir argüman olarak alır

İşte şablonun kısaltılmış Express bağlantısı. Doğrulayıcı SDK'ya aittir ve belirteci kimlik hizmetinin oturum biçimine tabi tutar: yalnızca HS256; iss, exp, iat ve jti zorunludur; en fazla bir saatlik kullanım ömrü; ve hiçbir MFA doğrulaması, kimliğe bürünme veya OAuth (yetki devri için açık standart) kaynak belirteci oturum olarak kabul edilmez.

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

Haklar koruması, bir rotanın hakkını dört adımda uygular. Hakkın never listesindeki bir rol, AUTHORITY_EXCEEDED ve barred ifadeleriyle reddeder ve hiçbir koltuk bunu kaldıramaz. roles içindeki bir rol, hak seat: true dediğinde aktif bir koltukla birlikte kabul eder. Aksi takdirde, hakkı taşıyan aktif bir koltuk kabul eder. Aksi halde istek, bir koltuk verebilecek kişileri belirterek AUTHORITY_EXCEEDED ile reddedilir. Korumaya bir depo (rights: { manifest, store: { pool, schema } }) verirseniz koltukları çağrıyı yapanın kendi kapsamı altında okur; bir licence belirten bir hak ayrıca aşağıda ele alınan bir lisans okuyucusuna ihtiyaç duyar.

Bir işleyicinin içinde, çözümlenmiş kapsamı okumanın tek yolu scopeOf(req) öğesidir ve koruma çalışmadıysa hata fırlatır. Herhangi bir rota eşleşmeden önce çalışan, bir önek üzerine kayıtlı bir koruma 500 MIDDLEWARE_ORDERING_ERROR yanıtı verir; kodunuzun kaydettiği ancak bildirimin beyan etmediği bir rota 500 UNHANDLED_ERROR yanıtı verir. Her ikisi de güvenli bir şekilde kapanarak başarısız olur (fail closed).

Platformun çağırdığı şablonun /internal rotaları diğer rejimi kullanır. Hizmet koruması sabit zamanda X-Service-Key kontrolü yapar ve kiracıyı platformun X-Organization-ID öğesinden alır, MISSING_SERVICE_KEY, INVALID_SERVICE_KEY veya MISSING_ORG_ID_HEADER öğelerini reddeder. Platformun imzalı çağrı başına belirteci için SDK'da requireService (Fastify) ve serviceMiddleware (Express) bulunur; bunlar ayrıca belirtecin hangi beceri ve rota için üretildiğini kontrol eder ve iki kez kullanılan bir belirteci reddeder.

Veritabanı sınırı: tenantFence ve withScopedTx

Kapsamlı bir tabloya yönelik her ifade sınırı oluşturur ve kapsamlı bir işlem (transaction) içinde çalışır:

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), çözümlenmiş bir kapsamdan koşulu ve parametrelerini oluşturur. Kişisel tablolar için owner öğesini geçirin; sahibin kaynak (provenance) olduğu kuruluş yapıtları için bunu dışarıda bırakın. İfadenin zaten parametreleri olduğunda, startIndex sınıra numaralandırmaya nereden başlayacağını söyler. Bir ekleme (insert) işlemi eksenleri asla girdi olarak almaz: kapsamdan scope.tenant, scope.owner ve scope.unit yazar.

withScopedTx, şemanın tek bağlama işlevi aracılığıyla tek bir işlem için her üç ekseni bağlar, ardından geri çağırma (callback) işlevinizi çalıştırır. Aynı işlemdeki ikinci bir bağlama SCOPE_ALREADY_BOUND hatası verir (500: kodunuz iki kez bağladı; çağrıyı yapan yanlış bir şey yapmadı). Eksik veya sıfır olan bir kiracı ya da sahip SCOPE_PREDICATE_INVALID hatası verir (403). Ayar işlemle sınırlıdır (transaction-local), bu nedenle havuzlanmış bir bağlantı bir kiracıyı bir sonraki isteğe taşıyamaz.

İki kardeş işlev, bir kişinin isteği olmayan durumları kapsar. withTenantScopedTx, bir makinenin okuduğu satırlar (cihaz kayıt defteri) için sahip olmadan kiracı ve birimi bağlar ve bir sahip taşıyan kapsamı reddeder. maintenanceScope(reason), sahibinin işlemi açılmadan önce kuruluş çapındaki bir işlemin ne olduğunu açıkça belirtmesini sağlar. Kod sınırı ve zorunlu satır düzeyinde güvenlik, tek bir kural için iki mekanizmadır; önyükleme kontrolü, veritabanı ikincisinin geçerli olduğunu kanıtlayana kadar dinlemeyi reddeder (aksi takdirde DB_ROLE_BYPASSES_ISOLATION).

Her ret bir satırdır

Şablon, gövde ayrıştırıcısı ile yönlendiriciler arasına bir kez olmak üzere bir ara katman yazılımı (middleware) daha kurar: ret defteri.

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

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

Yanıtı sarmalar, böylece bir kişinin okuduğu her ret —ister haklar korumasından, ister bir işleyiciden veya bir depodan gelsin— gövde gönderilmeden önce o kişinin kendi kapsamlı işlemi içinde şemanızın refusal tablosuna yazılır. Anonim bir 401 hiçbir şey yazmaz. Satır yazılamazsa, yanıt UNHANDLED_ERROR olur: ürünün kaydedemediği bir "hayır", kaydedilmiş gibi gönderilmez. Önyükleme, tablonun defterin satırını alıp alamayacağını kontrol etmek için assertRefusalLedger çalıştırır ve bir depo, her reddin ilgili olduğu kaydı belirtmesi için noteSubject({ recordId, isDemo }) çağrısı yapabilir. Bir müşteri geçen salı birinin neden geri çevrildiğini sorduğunda, yanıt bir tahmin değil, bir sorgudur.

Tek geçiş: kayıtlı bir salt okunur yetki

Müşterilerinizden biri diğeri için iş yaptığında ve diğeri bunu inceleyebildiğinde, sınırı geçmenin onaylanmış tek bir yolu vardır. Satırları tutan kuruluş bir yetki (grant) kaydeder. Okuyucunun kuruluşu, never içinde owner ve admin belirtmesi gereken granted.read hakkını taşıyan bir koltuk aracılığıyla bir kişiyi kabul eder. Okuma işlemi, yalnızca databases[].granted öğesinin listelediği tabloları seçebilen altıncı bir veritabanı rolü olan okuma koltuğu olarak çalışır:

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 önce okuyucunun kendi kiracısına bakma kaydını (look) yazar, ardından okuma koltuğunu yetkiye bağlar, bu da bakma kaydını sahibinin kiracısına yazar. Veritabanının kendi politikası, yetkinin okuyucunun kuruluşunu belirttiğini, tabloyu kapsadığını, başladığını, bitmediğini ve geri çekilmediğini ve bu işlemin kendi bakma kaydını yazdığını kontrol eder. Bakma kaydını atlayan bir okuma hiçbir şey görmez. Önyükleme sırasında assertSeatAtBoot(seatPool, schema), seat.url öğesinden açılan havuzun gerçekten koltuk olduğunu ve fazlası olmadığını kontrol eder, aksi takdirde DB_SEAT_ROLE_INVALID ile reddeder.

UNO üzerinden dağıtım (dispatch)

Tüm hesaplamalar, kapalı bir izin listesiyle tek bir dosyada oluşturulmuş tek bir istemciden geçer:

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

İzin listesi kasıtlı olarak modül düzeyinde bir sabittir. Bir operatör bunu yapılandırmadan genişletebilseydi, rota tüm kayıt defteri için bir gönderim vekili (dispatch proxy) haline gelirdi. Şablonun kendi testi, listenin tam olarak bildirimin derlendiği iş türlerini belirttiğini doğrular.

Zarf

Bir gönderim, zorunlu çekirdeğinde altı alan taşır. İstemci, kiracı ve aktörü asla istekten değil, doğrulanmış kapsamdan doldurur:

Alan Ne barındırır
jobType Ad alanı (namespace) belirtilmiş iş türü, <plugin name>.<skill id>
organizationId Kapsamdan gelen kiracı
userId Denetim ve faturalandırma için kapsamdan gelen aktör
inputParams Becerinin girdisi. Asla bir kiracı kimliği taşımaz; taşıyan bir girdi gönderim sırasında reddedilir
priority critical, high, normal veya low
pluginId Bildiriminizin name öğesi. Her gönderim kaynak eklentisini beyan eder

İsteğe bağlı alanlar arasında correlationId (bir UUID (evrensel olarak benzersiz tanımlayıcı) veya yeni bir tane üretilir) ve işçinin sonucunu nereye göndereceğini bilmesi için bir plugin_queue becerisinin ihtiyaç duyduğu callbackUrl bulunur.

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, ardından yoklama (polling)

Her gönderim kuyruğa alınır. Yanıt her zaman tanımlayıcılarla (jobId, runId, traceId, status) birlikte 202 olur, asla bir sonuç olmaz. Sonuç, işin yoklanmasından (polling) veya geri çağırma işlevinizden gelir. uno.peek(jobId, { scope }) bunu bir kez okur ve awaitJob sonlandırıcı bir duruma kadar yoklar; her ikisi de kiracıyı doğrulanmış kapsamdan gönderir ve her ikisi de ağ çağrısının sizin tarafınızda döndürülen satırın organization_id öğesini çağrıyı yapanın kiracısına karşı kontrol ederek, bir uyuşmazlığı SCOPE_REFUSED ile reddeder.

Çalıştırma satırını kendi yazımıyla okuyun. Gönderim yanıtı jobId der; satır job_id, organization_id ve plugin_id der. Sonuç ve hata sütunları result, error, error_code ve error_troubleshooting şeklindedir. completed ve failed sonlandırıcıdır. timed_out, cancelled ve system_failure temizleyiciden (reaper) gelir ve geç kalan bir sonuç bunları yine de düzeltebilir. Bunlardan herhangi birini ayrıştırılamaz olarak değerlendiren bir istemci, platformun her gün yazdığı satırları reddeder.

Onay bekletmesi

approval beyan eden bir bildirim becerisi gönderimde bekletilir. 202 bu durumda status: "awaiting_approval" der ve bildirimin verdiği nedenle birlikte bir waitpointId taşır. Çalıştırma, adı belirtilen bir kişi bu konuda karar verene kadar bekletilir. uno.approve ve uno.resolveWaitpoint, kiracıyı ve çağrıyı yapanı aktör olarak gönderir ve doğrulanmış çağrıyı yapandan başka biri tarafından verilen bir karar reddedilir. Bir onay işi bir kez serbest bırakır ve gönderim kontrollerini tekrar çalıştırır; bir ret ise işi failed ile sonlandırır. İkinci bir karar reddedilir ve bekletme süresi dolduktan sonra verilen bir karar da reddedilir. Ürününüz onaylayıcının öneriyi yapandan farklı bir kişi olmasını gerektiriyorsa, bunu karar veren rotada zorunlu kılın: platform her ikisini de kaydeder.

Bekletilen bir işi bekletiliyor olarak gösterin. Çalıştırma satırı öyle söyleyene kadar bir kişiye tıklamasının işi serbest bıraktığını söylemeyin.

YZ: beceri satırındaki istekler ve tek bir okuma

Eklentiniz asla bir modeli çağırmaz. Bir bildirim becerisi bir modele ihtiyaç duyduğunda (core veya verified güven düzeyinde, llm_only veya tool_using), tercihleri kayıt defteri satırında ifade edersiniz ve yönlendirici kuruluşun kendi havuzundan karar verir:

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

preferredProvider ve preferredModel, yönlendiricinin yalnızca kuruluşta o sağlayıcı etkinleştirilmiş ve kimlik bilgileri tanımlanmış olduğunda dikkate aldığı isteklerdir. capabilityProfile filtreler ve asla seçmez; dataResidency öğesi (eu_only, us_only veya any) yönlendiricinin karşıladığı veya reddettiği kesin bir kısıtlamadır. Hepsini dışarıda bırakmak genellikle doğrudur. modelOverride, tam olarak belirli bir modele ihtiyaç duyan nadir beceriler için vardır ve yanındaki istekleri etkisiz hale getirir; beceri başka herhangi bir modelde anlamsız olmadığı sürece bundan kaçınırdım.

Arayüzünüzün yönlendiricinin hangi modeli kullanacağını göstermesi gerektiğinde, bunu tahmin etmeyin, okuyun:

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

createAIRouteClient(...).effectiveRoute(), AI Provider Router'ın onaylanmış tek okuma yöntemidir. Ağ geçidinin adresini, çağrıyı yapanın kendi hamil (bearer) belirtecini ve platformunuzun kısa adını (slug) alır ve hiçbir YZ isteği göndermez. Sağlayıcıyı ve modeli, politikanın izin verdiği sağlayıcıları ve seçilen uç noktanın local mi yoksa external mı çalıştırdığını yanıtlar. Rota kullanılabilir olmadığında, asla varsayılan bir model değil, yönlendiricinin reddini sözcüklerle (çözümüyle birlikte NO_PROVIDER_FOR_ROLE, MODEL_CAPABILITY_UNAVAILABLE veya NO_MODEL_FOR_ROLE_AND_PROVIDER) yanıtlar. Bu reddi kişiye gösterin; konuşan kendi kuruluşlarının yapılandırmasıdır.

Lisans kontrolleri

Üç mekanizma, üç ayrıntı düzeyinde lisanslamayı kontrol eder.

Bir lisans belirten hak. En basiti. Bildirimde bir hak licence: "<feature>" taşır ve koruma, herhangi bir rol okunmadan önce çağrıyı yapanın kendi belirteciyle kimlik hizmetine kuruluşun lisansının bunu taşıyıp taşımadığını sorar. Korumayı bir okuyucu ile oluşturun:

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

Özelliği taşımayan bir lisans, neyin taşıdığını belirterek ve kuruluşun sahiplerinin ve yöneticilerinin bunu açabileceğini söyleyerek herkesi LICENCE_LOCKED ile reddeder. Okunamayan bir lisans UNHANDLED_ERROR ile reddeder: kilitli bir özellik, lisansa ulaşılamadığı için asla sunulmaz. Yanıtlar, kuruluş ve özellik başına 30 saniye boyunca hatırlanır.

Ürün kapısı. runtime/product-gate içinden createProductGate({ baseUrl, product }), yetkilendirme kontrolüne çağrıyı yapanın kuruluşunun ürününüze sahip olup olmadığını sorar ve middleware() öğesi kapsam korumasından sonra çalışır. Olumsuz bir karar ENTITLEMENT_DENIED şeklindedir; ulaşılamayan bir kontrol ENTITLEMENT_UNREACHABLE şeklindedir ve kapı asla birini diğeri gibi değerlendirmez.

Lisans belgesinin kendisi. Bir alan paketinin (domain pack) kapalı modülü gibi, imzalı lisanstan kendi başına karar vermesi gereken kod, runtime/licence-document içinden verifyLicenceDocument(docText, opts) kullanır. Bu saf bir işlevdir: ağ çağrısı yok, ortam değişkeni yok, dosya yok. Her iki imzayı da derlemenin taşıdığı güven köklerine karşı kontrol eder ve yetkiler, eklentiler ve alan paketleriyle birlikte bir durum (VALID, WARN, GRACE, RESTRICT, TERMINATE veya ABSENT) yanıtlar. Ardından licenceAllows(verdict, featureGroup, action, tenantId?), bir grup altında use veya provision yapıp yapamayacağınızı söyler. RESTRICT, use işlemine izin verir ve provision öğesini LICENCE_LOCKED ile yanıtlar, böylece çalışan işler devam eder ve yeni hiçbir şey başlamaz.

Test etme

Şablonun testleri modeli gösterir; arkasındaki araçlar şunlardır.

Kapsam taklitleri (fakes). Çözümlenmiş kapsam kopyasını test/scope-fakes.ts içinde bir kez oluşturun ve eksik durumlar da dahil olmak üzere her yere enjekte edin: birim yok, belirteç yok, sıfır kuruluşlu bir belirteç. Ret yolları ürünün kendisidir.

Sahte bir gönderim aktarımı. UnoClient; fetch, now ve sleep alır, böylece bir birim testi asla ağa dokunmaz. Zarfın alanlarını, 202 şeklini, organization_id öğesiyle sonlandırıcı bir satıra kadar yapılan yoklamayı ve başka bir kiracıya ait satırın düşürüldüğünü doğrulayın.

Gerçek bir Postgres. Sahte bir sorgu işlevi bir SQL dizesini kanıtlar. Zorunlu satır düzeyinde güvenliğin geçerli olduğunu veya dosyaların taşıyıcı (migrator) olarak sırayla uygulandığını kanıtlayamaz. testing/ephemeral-postgres kullan-at bir sunucu başlatır ve üretim ortamının çalıştırdığı aynı nexus-migrate öğesini çalıştırır:

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 (sürekli entegrasyon) dışında, Postgres sunucusu olmayan bir makine her veritabanı senaryosunu çözümüyle birlikte ismen atlar, asla yeşil (başarılı) dönmez. CI içinde aynı eksiklik paketi başarısız kılar (EPHEMERAL_POSTGRES_UNAVAILABLE_IN_CI), çünkü atlanan bir satır düzeyinde güvenlik testi hiçbir şey ölçmeyen yeşil bir kapıdır. Sunucu başlamak için 180 saniyeye kadar bekler ve test süreci sona erdiğinde bir gözetleyici (watchdog) onu durdurur.

Yalıtım koşum takımı (harness). testing/isolation-harness içinden runIsolationHarness(target), uygulamanızın bağladığı her rotayı okur ve her birine başka bir kuruluşun yöneticisi ve bir iş arkadaşı olarak saldırır. Ardından kod sınırı kaldırılmış, veritabanı sınırı kaldırılmış ve her ikisi de kaldırılmış olarak tekrar saldırır. Bir rota yalnızca her iki sınırdan biri yerindeyken saldırı başarısız olduğunda ve her ikisi de kaldırıldığında kurbanın verilerine ulaştığında PROVEN olur; böylece testin bir sızıntıyı gerçekten görebildiğini bilirsiniz. Her rotanın beyan edilen sorgusunu ve örnek gövdesini gönderir, böylece boş bir isteği reddeden bir rotaya yine de ulaşılır. Bir testte ledgerOf(report) öğesini sabitleyin ve defectsOf(report) durumunda başarısız olun.

Kayıt: bildirimden (manifest) beceri kayıt defterine

Bildirim becerileriniz beceri kayıt defterine tek bir yoldan ulaşır:

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

compileRegistry, doğrulanmış bir bildirimi nexus.plugin-sync/v1 gövdesine dönüştürür. Şablon bunu içe aktarma sırasında yapar, böylece geçersiz bir bildirim derlemeyi başarısız kılar:

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

Eşitleme bildirimseldir (declarative): her seferinde tüm beceri kümesini gönderin; dışarıda bırakılan bir beceri, geçmişi korunarak devre dışı bırakılır. Katıdır: bilinmeyen bir alan, başka bir katmana ait bir alan veya bir null reddedilir, tüm ihlaller tek bir 400 SYNC_CONTRACT_VIOLATION içinde birlikte geri döner ve bir ihlal varken hiçbir şey yazılmaz. Ve beceri başına, ad alanı belirtilmiş iş türüne göre anahtarlanmış, göndericinin okuduğu her sütunu taşıyan bir kayıt defteri satırı yazar; böylece eşitleme 200 yanıtı verdiği anda beceri çalıştırılabilir olur.

Kimliği doğrulanmış çağrıyı yapan, asla bir gövde alanı değil, eklentinin kendisidir. Eşitlemeyi, mTLS (karşılıklı TLS: her iki uçta bir sertifika bulunan Taşıma Katmanı Güvenliği) üzerinden eklentinizin kendi iş yükünden çağırın. Skills Engine, iş yükünüzün SPIFFE kimliği (spiffe://<trust-domain>/ns/<namespace>/sa/<service-account>) ad alanını ve hizmet hesabını belirten istemci sertifikasını okur ve o ad alanı için kaydedilen eklentiyi ve sahip kuruluşu arar. Gövdenin pluginId öğesi eşleşmelidir; bu bir seçici değil, bir kontroldür. Her satır o eklenti ve kuruluşla yazılır.

Durum Kod Anlamı
200 {contract, pluginId, version, created, updated, unchanged, disabled, skills}
400 SYNC_CONTRACT_VIOLATION violations[] içinde listelenen her ihlal; hiçbir şey yazılmadı
401 UNAUTHORIZED Hatalı veya eksik hizmet anahtarı
401 CALLER_IDENTITY_UNVERIFIED Okunabilir istemci kimliği yok
403 DELIVERY_IDENTITY_MISSING Çağrıyı yapan ad alanı hiçbir eklentiye ait değil
403 PLUGIN_ID_MISMATCH Gövde başka bir eklenti adı veriyor
409 REGISTRY_CONFLICT Bir iş türü başka bir yere ait veya eşitleme dışında kaydedilmiş; hiçbir şey yazılmadı

Dağıtım adımınızı 200 dışındaki herhangi bir durumda başarısız kılın. Başka hiçbir durum becerilerinizin kaydedildiği anlamına gelmez.

İlk kullanıma hazırlama (Onboarding)

Devreye alma, her biri kendi başına yeniden çalıştırılabilen, iptal edilebilen veya geri alınabilen sıralı on adım olarak çalışır:

  1. Depoyu klonlayın ve doğrulayın.
  2. Bildirimi ayrıştırın.
  3. Güvenlik sorunları için tarayın.
  4. İmajı oluşturun.
  5. Kurulumun kayıt defterine gönderin (push).
  6. Alan adlarını ayarlayın.
  7. Kurulumun sürüm kanalları aracılığıyla dağıtın.
  8. Sağlık kontrolünü bekleyin.
  9. Eklentiyi kaydedin.
  10. Geliştiriciye bildirin.

Dağıtımdan önce, bildirim ve oluşturulan imaj üzerinde beş uyumluluk kontrolü çalışır: bildirim ayrıştırılır ve zorunlu alanlarını taşır; beyan edilen her rota gerçek bir kayıtlı rotadır; eklenti kendi şemasına sahiptir ve bunun dışına hiçbir şey yazmaz; kaynak istekleri beyan edilmiştir ve sınırlar içindedir; ve imajın çalışan bir sağlık işleyicisi vardır. Önyükleme sırasında kendini kaydeden bir eklenti, aynı sözleşmeyi kendi yetkisi altında çalıştırır, böylece kontroller işlem hattının (pipeline) değil kendi CI süreci haline gelir. Birini atlamak devreye almayı kısaltmaz; hatayı çalışma zamanına taşır.

Bildiriminizdeki markalama, alan adına göre kimlik doğrulaması olmadan sunulur, çünkü oturum açma sayfası henüz kimsenin kimlik bilgisi yokken buna ihtiyaç duyar. branding içindeki her şeyi herkese açık olarak değerlendirin.

Ortamlar ve yükseltme
Ortamlar ve yükseltme
Ortamlar ve yükseltme, her kapıyı ve durumunu tek bir sayfada göstererek her sürümü geliştirme alanından hazırlık (staging) aşaması üzerinden pilot birime, ardından tüm birimlere taşır. Bir kapıyı atlayan yükseltme GATE_CANNOT_BE_SKIPPED ile reddedilir.
Kanallar ve kurulumlar
Kanallar ve kurulumlar
Kanallar ve kurulumlar, hata oranlarını asla içerik olarak değil sayı olarak vererek hangi birimin hangi sürümü çalıştırdığını gösterir. Bir birimi geri almak, yalnızca o birime dokunan incelenmiş bir değişikliktir.

Çalışma zamanının sizin için yapmayacağı şeyler

Çalışma zamanı yalıtım, gönderim ve model erişimi konusunda sınırı korur. Ürün mantığınızı doğru hale getirmez ve yavaş bir sorguyu hızlandırmaz: her ifade, bildiriminizin db bloğunun beyan ettiği zaman aşımlarıyla bağlı bir işlem içinde çalışır ve statementTimeoutMs süresini aşan bir ifade beklenmez, iptal edilir. Sorgularınızı buna göre boyutlandırın. Ayrıca onay bekletmesi, okuma koltuğu ve lisans okuyucusunun tümü bir gidiş-dönüş (round trip) veya bir işlem ekler. Anomali inceleme eklentimde lisans kontrolü, 30 saniyelik belleği ısınana kadar istek başına birkaç milisaniye ekledi ki bu, kilitli bir özelliği asla sunmamak için adil bir bedeldi.