Oturum açınToplantı planlayın

Bölüm 2.21

Plugin SDK

Plugin SDK'nın (yazılım geliştirme kiti) kurulumu, komut satırı araçları, tam hizmet şablonunda bir gezinti, alan alan v2 bildirimi (manifest) ve bir eklentiyi kurallara bağlı tutan yirmi iki geçit.

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

22 dakikalık okuma

İkinci eklentim ilkinin üçte biri kadar zaman aldı ve bu tasarrufun neredeyse tamamı SDK (yazılım geliştirme kiti) sayesindeydi. İlkinde bir kapsam denetimi, bir yapılandırma yükleyicisi ve bir taşıma çalıştırıcısı yazdım ve bir incelemeci bunların her birini geri gönderdi. İkincisinde ise tek bir iskelet oluşturma komutu çalıştırdım, örnek duygu analizi becerisini sildim ve günlerimi uçuş dinamiği ekibimizin gerçekten ihtiyaç duyduğu anomali inceleme kayıtları üzerinde geçirdim.

@adverant-nexus/plugin-sdk tek bir npm paketidir. İçinde v2 bildirim şemasını ve onu okuyan doğrulayıcıları (definePlugin, defineSkill), eklentinizin kapsam, veritabanı, yönlendirme ve diğer işlemler için içe aktardığı çalışma zamanı modüllerini, test yardımcılarını, uyumluluk geçitlerini ve komut satırı araçlarını barındırır. Bu bölüm paketin kurulumunu, araçları, şablonu, bildirimi ve geçitleri ele almaktadır. Eklenti çalışma zamanı başlıklı Bölüm 2.22, çalışan kodunuzdaki çalışma zamanı modüllerini kapsar.

Kurulum

Paket, herkese açık npm kayıt defterinden değil, her zaman Adverant'ın https://registry.adverant.ai/npm/ adresindeki kayıt defterinden gelir ve hesabınızın "Pull tokens and install commands" sayfasındaki çekme belirtecine (pull token) ihtiyacınız vardır. Deponuzun .npmrc dosyasında @adverant-nexus kapsamını kayıt defterine yönlendirin:

@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>

<pull-token>, hesap sayfanızdan alınan belirteçtir. Bir işlem hattında (pipeline), bunu gizli bilgiden (secret) aktarın ve asla depoya işlemeyin (commit etmeyin); şablonun Dockerfile dosyası bu belirteç olmadan derlemeyi reddeder ve npm ci çalıştıktan sonra .npmrc dosyasını derleme aşamasından siler, böylece belirteç asla bir imajın içinde gönderilmez.

Ardından sürümü tam olarak sabitleyin:

npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0

İlk kurulumda package-lock.json dosyasını depoya işleyin. Şablonun imaj derlemesi npm ci komutunu çalıştırır ve npm install komutuna geri dönmeyi reddeder: kilit dosyası (lockfile) sözleşmedir. SDK'nın kendi alt sınırı Node 18'dir; şablon ise Node 20'yi hedefler.

Komut satırı araçları paketin içinde gelir, bu nedenle bu dokümantasyondaki her komut, paketi ve sürümünü npx -p ile belirtir. Tek başına kullanıldığında npx create-nexus-plugin herkese açık kayıt defterinde aranır ve o ad bu pakete ait değildir.

Komut satırı araçları

Araç Yaptığı iş
create-nexus-plugin Bir eklenti iskeleti oluşturur, bir bildirimi doğrular, v1 bildirimini v2'ye taşır ve ön uç (frontend) geliştiriciniz için tüketici kılavuzunu oluşturur
nexus-tenancy Şemanızın çoklu kiracı (tenancy) SQL'ini bildirimden oluşturur: roller, yetkiler, satır düzeyinde güvenlik şablonu ve graf tabloları
nexus-migrate Taşımalarınızı (migrations) uygular: rolleri bir kez sağlar, ardından numaralandırılmış her dosyayı taşıyıcı (migrator) rolüyle çalıştırır
nexus-gates Her uyumluluk geçidini ve her geçidin kendi iç testini çalıştırır

create-nexus-plugin hiçbir ağ çağrısı yapmaz ve uzaktan kod yüklemez. Platformun sisteme dahil etme sürecinin çalıştırdığı aynı süreç içi doğrulayıcıları çalıştırır; böylece "benim makinemde doğrulandı" ile "platform bunu kabul etti" arasında hiçbir sapma olmaz.

Eylem Bayraklar Yaptığı iş Çıkış kodları
scaffold <name> --tier full-service\|ui-only\|skills-only, --dir <path>, --print Yeni bir eklenti dizini yazar; --print yalnızca bildirimi yazdırır 0 yazıldı · 1 üzerine yazmayı reddetti · 2 hatalı kullanım
validate <file> Bir nexus.manifest.json dosyasını veya bunu dışa aktaran bir .ts ya da .js modülünü doğrular 0 geçerli · 1 geçersiz veya okunamıyor · 2 hatalı kullanım
migrate <file> --write Bir v1 bildirimini v2'ye yükseltip yazdırır veya yerinde üzerine yazar 0 · 1 · 2, yukarıdaki gibi
guide --manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint Bildirimden ve anlatımınızdan tüketici kılavuzunu oluşturur; --check depoya işlenmiş kopyayla karşılaştırır ve hiçbir şey yazmaz 0 · 1 sapma veya lint ihlali · 2 hatalı kullanım
help Kullanımı yazdırır 0

İskelet oluşturma (scaffolding) ve üç katman

npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-service

--tier varsayılan olarak full-service değerini alır. İskelet oluşturucu mevcut bir dizine yazmayı reddeder ve yazdığı bildirim doğrulamadan halihazırda geçmiştir; asla geçersiz bir bildirim üretmez.

Katmanı, eklentinizin ne içerdiğine göre seçin.

Katman İçeriği Bildirmesi gereken
skills-only Yalnızca bildirim becerileri En az bir kayıt içeren skills[]
ui-only Kabuk (shell) içinde bir ön uç yüzeyi frontend
full-service Genellikle kendi şemasına sahip bir arka uç (backend) ve bir ön uç backend ve frontend; ve bir arka ucu olduğu için runtime.healthCheck

Emin değilseniz full-service iskeletini oluşturun ve ihtiyacınız olmayanları silin. Tam tersi yönde ilerlemek, şablonun size hazır vereceği parçaları kendinizin yazması anlamına gelir.

Tam hizmet şablonunda bir gezinti

Şablon, sonraki her bölümün varsaydığı katı modele göre oluşturulmuş referans eklentidir. Örnek mantığını değil, şeklini klonlayın.

Yol Tanımı
nexus.manifest.json v2 bildirimi: yeniden ifade edilen üç yasa, rota tablosu ve haklar kaydı
src/config.ts Yapılandırma yükleyicisi. Tek bir spesifikasyon, bir kez okunur, süreç başlatmayı reddetmeden önce her sorun toplanır
src/scope.ts SDK'nın katı belirteç doğrulayıcısı ve iki rejimle (bir kişinin hamiline belirteci ve platformun servis çağrısı) bir isteği kapsama dönüştüren tek dosya
src/db.ts Her ifade tenantFence() oluşturur ve withScopedTx içinde çalışır
src/uno.ts Tek yönlendirme dosyası: tek URL, tek istemci, kapalı bir izin listesi
src/routes/*.ts health (anonim, tam yol), /api rotaları (kapsamlı) ve /internal geri çağrısı (servis korumalı)
src/skills/sentiment.ts Deterministik bir host_callback becerisi; sözlüğü kendi mantığınızla değiştirin
src/server.ts Bileşim kökü (composition root): ret defterini bir kez kurar, veritabanını bekler (sınırlı süreli), ardından dinlemeye başlamadan önce yalıtım ve defter denetimlerini çalıştırır
migrations/000_tenancy.sql İskelet oluşturma sırasında nexus-tenancy render tarafından oluşturulur: roller, şema, satır düzeyinde güvenlik şablonu
migrations/001_init.sql Kiracı öncelikli bileşik anahtara ve bileşik, kiracı taşıyan yabancı anahtara sahip iki tablo
migrations/002_refusal_ledger.sql Ret defterinin yazdığı tablo
scripts/ci/required-env Başlatma için gerekli ortam değişkeni adlarını JSON olarak yazdırır
scripts/ci/shadow-migrate-*.sh İşlem hattının nexus-migrate üzerinden taşıma prova çalıştırması (dry run)
gates/ Geçitlerin muafiyet dizini: boştur, yeni bir eklenti için doğru durum budur
test/ Her testin enjekte ettiği kapsam dublörleriyle (test doubles) kapsam, rotalar, veritabanı, yönlendirme ve başlatma testleri
Dockerfile İçinde taşımaları barındıran, root olmayan bir imaj (kullanıcı kimliği 10001)

Bu dosyalardan birkaçına daha yakından bakmak faydalı olacaktır.

src/config.ts iki kural izler. Hata fırlatmadan önce her sorunu toplar; böylece her birinde tek bir eksik değişkeni belirten beş yeniden başlatma yerine, tek bir yeniden başlatma eksik olan beş değişkenin tümünü belirtir. Ve bir değere yalnızca yanlış bir değer sessizce yanlış bir yanıt üretemeyeceğinde varsayılan değer atar: yanlış bir bağlantı noktası bağlanmayı görünür şekilde başarısız kıldığı için PORT varsayılan olarak 8080 değerini alabilirken, DATABASE_URL ve UNO_DISPATCH_URL zorunludur ve küme içi adresler olmalıdır. Herkese açık bir adres başlatma sırasında reddedilir.

node scripts/ci/required-env
["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]

Şablonun kendi testi bu dosyayı çalıştırır ve çıktısını yapılandırma spesifikasyonunun zorunlu olarak işaretlediği adlarla karşılaştırır; böylece listeyi güncellemeden zorunlu bir değişken eklemek npm test adımının başarısız olmasına neden olur.

src/server.ts, veritabanı yanıt verene kadar dinlemeye başlamaz ve her başarısız denemeyi nedeniyle birlikte günlüğe kaydederek beklemeyi 120 saniye ile sınırlar. Ardından, sırasıyla, uygulama rolünün kiracıyı yeniden bağlayamadığını ve her tablonun satır düzeyinde güvenliğe zorlandığını, her podun havuzunun rolün bağlantı sınırına uyduğunu ve ret defteri tablosunun bir satır alabildiğini kanıtlar. Bu üçünden herhangi birinden gelen bir ret tam olarak yazdırılır ve süreç 2 koduyla çıkar.

Alan alan v2 bildirimi (manifest)

Bildirim, eklentinin platformla yaptığı makine tarafından okunabilir sözleşmedir. Siz onu yazarken, platform onu sisteme dahil ederken ve sonrasında sürekli olarak doğrulanır. Şema her düzeyde additionalProperties: false niteliğindedir: eklentinizin bir bölümü varsa, bunun için bir özellik vardır ve bildirilmemiş bir anahtar reddedilir. Çözüm her zaman doğru isteğe bağlı özelliği kullanmaktır.

Zorunlu çekirdek

Alan Kural
manifestVersion Tam olarak "2". Bir v1 belgesi taşınır, asla yerinde yeniden doğrulanmaz
name ^[a-z0-9]+([-.][a-z0-9]+)*$, en fazla 64 karakter. Kayıt, yönlendirme ad alanı (namespacing) ve kiracı kapsamlı satırlarda kullanılan eklenti kimliği. Beceriler bildiren bir eklentinin ayrıca nokta içermeyen ve rakamla başlamayan bir ada ihtiyacı vardır
displayName 1 ila 120 karakter
version Anlamsal sürüm (semantic version); kendi yayın treniniz
description, author, license Her biri en az bir karakter
tier skills-only, ui-only veya full-service
trust core, verified, community veya untrusted
runtime Zorunlu: executionMode, isolationLevel (1 ila 4), entrypoint. İsteğe bağlı: nodeVersion, healthCheck, readinessCheck, livenessCheck, her biri / ile başlayan bir yol. Mod, düzeyden türetilir: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker
architecture compute, ai ve deploy, yeniden ifade edilen üç platform yasası. Doğrulayıcı ifadeleri sabitler

Kendi kurulumunuz için oluşturduğunuz bir eklentide bu üç cümle aşağıdaki gibidir. ai cümlesi yapay zekayı (YZ) kapsar ve eklentinin hiçbir model kimlik bilgisi barındırmadığını belirtme yeridir.

"architecture": {
  "compute": "All compute runs via UNO dispatch (nexus-orchestrator /api/v1/dispatch + nexus-workflows). No direct engine, queue or model-provider calls from plugin code.",
  "ai": "All AI goes through the AI Provider Router, which alone owns the credential and the final provider/model decision. This plugin holds no model credentials.",
  "deploy": "Deploy is through the installation's release channels only."
}

Rota tablosu: api ve rights

api için version ve basePath gereklidir ve isteğe bağlı olarak websocket (path, auth) ve endpoints[] alır. Rota tablosu şemadaki en güçlü fikirdir: bir geçit, bunu kodunuzun gerçekten kaydettiği rotalarla her iki yönde karşılaştırır (diff alır), böylece bildirim sadece bir dokümantasyon değil, denetlenebilir bir sözleşme olur.

Her uç nokta için method (GET, POST, PUT, PATCH veya DELETE) ve path gereklidir. Geri kalanlar:

Alan Ne söyler
auth Beş sınıftan biri: scope (bir kişinin rotası, kapsam korumasının arkasında), service-key ve internal (sunucudan sunucuya, bir tarayıcıdan asla erişilemez), public (her zaman yalnızca allowAnonymous ile tam bir yol) ve device (kendi kimlik bilgisine sahip bir makine, cihaz korumasının arkasında)
right Kapsam korumasının hizmet verdiği her rotada zorunludur ve diğer tüm rotalarda reddedilir: rights kaydındaki bir hakkın adı
needsUnit Çağıranın birimi çözümlenemediğinde rota reddeder
allowAnonymous Yalnızca tam eşleşmeli izin listesi. Bir önek kuralı, /health-of-tenant-42 öğesinin herkese açık hale gelmesine yol açar
group, serves, screens Bir release bloğu altında: rotanın hizmet verdiği yetenek grubu, o grubun lisanslı özelliği kilitlendiğinde ne yanıt verdiği (data, teaser, sighting veya ask) ve hizmet verdiği ekranlar
query required (her ad bir örnek değerle birlikte) ve allowed: rotanın okuduğu sorgu parametreleri
body example: bir yazma rotasının örnek gövdesi, kendi doğrulayıcısının kabul ettiği bir gövde. Asla bir GET üzerinde bulunmaz

rights, bu rotaların adlandırdığı kayıttır. Her hakkın roles (tavan) özelliği ve isteğe bağlı olarak summary, never (başka neye sahip olurlarsa olsunlar bu hakkı asla kullanamayacak roller), barred (bir never rolünü reddetmek için ürünün kendi ifadeleri), seat (canlı bir koltuk da gereklidir), self (kendi oturumları üzerindeki haklar için doğrulanmış her kişi buna sahiptir), grants (sahipleri koltuk verir; en fazla bir hak bunu belirtir), licence (kuruluşun lisansının taşıması gereken lisanslı bir özellik), installation (yalnızca kurulumun kendi yöneticileri tarafından sahip olunur) ve platform (yalnızca Adverant'ın platform yöneticileri tarafından sahip olunur; hiçbir rol belirtmez) özellikleri vardır. Hak adlarında en az bir nokta bulunur: project.read, money.pay.

"api": {
  "version": "1",
  "basePath": "/",
  "endpoints": [
    { "method": "GET", "path": "/health", "summary": "Liveness", "auth": "public", "allowAnonymous": true },
    { "method": "GET", "path": "/api/projects", "summary": "List the caller's projects", "auth": "scope", "right": "project.read" },
    { "method": "POST", "path": "/api/projects", "summary": "Create a project", "auth": "scope", "right": "project.create" },
    { "method": "POST", "path": "/internal/skills/sentiment_score", "summary": "host_callback receiver", "auth": "service-key" }
  ]
},
"rights": {
  "project.read": { "summary": "Read the organisation's projects.", "roles": ["owner", "admin", "member", "viewer"] },
  "project.create": { "summary": "Open a project.", "roles": ["owner", "admin", "member"] }
}

definePlugin, hakkı olmayan bir kapsam rotasını (ENDPOINT_RIGHT_MISSING), kayıtta bulunmayan bir hakkı (ENDPOINT_RIGHT_NOT_REGISTERED) ve hiçbir korumanın hizmet vermediği bir rotadaki hakkı (ENDPOINT_RIGHT_UNGUARDED) reddeder. Ayrıca kendiyle çelişen bir kaydı ve tek bir rotanın iki farklı yazımını (:id ve :recordId) DUPLICATE_ENDPOINT olarak reddeder.

Verileriniz: databases, schema ve db

schema, eklentinin sahip olduğu tek Postgres şemasıdır. public, plugins, auth ve nexus yasaktır ve databases[] da bir Postgres şeması belirtiyorsa ikisi eşleşmelidir.

databases[], her veri deposunu motoruna göre bildirir: postgresql (schema, tables, migrations ve kayıtlı bir yetki altında başka bir kuruluşun okuyabileceği tablolar olan granted), neo4j (schemas), qdrant (collections) veya redis (purpose).

db, eklentinin açtığı her bağlantı için oturum sınırlarını tutar; hem incelemecinin hem de dağıtımın okuyabilmesi için kodlanmak yerine burada bildirilir:

Alan Sınırladığı şey
maxConnections Kopya (replica) başına havuz
pods Aynı anda havuz tutan en fazla pod sayısı, kopyalar artı kesintisiz güncelleme (rolling update) artışı. Her rolün bağlantı sınırı maxConnections × pods olarak oluşturulur; bunu dışarıda bırakırsanız definePlugin, DB_PODS_UNDECLARED uyarısını verir
statementTimeoutMs Tek bir ifade
idleInTransactionTimeoutMs Hiçbir şey çalıştırmayan açık bir işlem (transaction)
workMemKB Sorgu başına değil, düğüm başına tek bir sıralama veya karma (hash) düğümü
piiMask[] Kişisel verileri tutan, yönetilen SQL konsolunda ve günlüklerde maskelenen table.column kayıtları

Beceriler ve araçlar: skills, mcpTools, entitlements

skills[] bildirim becerilerini tutar; Beceriler başlıklı bölüm 2.20, bunların alanlarını ve katmanlarını kapsar. mcpTools[], eklentinin yayınladığı MCP (Model Context Protocol) araçlarını tutar; her biri bir name, bir description ve üst düzey oneOf, allOf veya anyOf içermeyen bir inputSchema öğesinden oluşur.

entitlements için featureIdPattern gereklidir ve alwaysOn[], source ile store kabul edilir. Desen, özellik kimliklerinizin içinde bulunduğu ad alanını belirtir; geleneksel olarak eklentinin name değeri artı kodunuzun yüzey başına doldurduğu bir segmenttir. alwaysOn[], hiçbir yetkilendirme (entitlement) kararı alınamadığında bile yanıt vermesi gereken kısa ve tam listedir: sağlık, hazırlık, oturum açma ve bir yöneticinin yetkilendirmeyi onarmak için ihtiyaç duyduğu ayarlar.

Değişiklik kontrolü: changePolicy

"changePolicy": {
  "enabled": true,
  "classes": ["website", "bff", "migration"],
  "approvals": { "website": 1, "bff": 1, "migration": 2 }
}

Onaylar farklı kişiler bazında sayılır ve değişikliği öneren kişi asla bunlardan biri değildir; bu iki koşul birden sağlanmazsa, "iki onay" bir kişinin iki kez tıklamasına dönüşür. enabled: true için classes gereklidir ve belirtilen her sınıfın kendi sayısına ihtiyacı vardır. Dışarıda bıraktığınız bir sınıf yönetilmez (ungoverned) durumdadır ki bu da şemanın size yazılı olarak beyan ettirdiği meşru bir seçimdir.

Kim olduğunuz: domains, branding, routing

domains[] (her biri primary ve aliases[]; domain tek etki alanı biçimidir) eklentinin nerede yanıt verdiğini listeler. branding için appName gereklidir ve tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId ile gaId kabul edilir. branding içindeki her şey herkese açıktır: oturum açma sayfası, henüz kimsenin kimlik bilgisi yokken bunu okur, bu nedenle asla bir gizli bilgi veya dahili adres barındırmaz. routing (type, gateway, virtualService), kendi yönlendirmesini tanımlayan eklentiler içindir.

Boyutlandırma ve geri kalanlar

resources için cpuMillicores (10 ila 64,000) ve memoryMB (16 ila 262,144) gereklidir ve diskGB, timeoutMs, port ile wsPort kabul edilir. backend; port, healthPath, apiPrefix, framework ve arka ucunuzun adıyla içe aktardığı SDK istemcileri olan platformClients[] öğelerini tutar. Liste kapalıdır ve bir geçit bunu içe aktarmalarınızla karşılaştırarak denetler. Şema on dört ada izin verir: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin ve uno, artı dahili bir adı koruyan, plan yetkilendirme retlerine yanıt veren istemci için bir ad. Özellik yetkilendirme istemcisi olan runtime/entitlements bunlardan biri değildir ve asla listeye girmez; çünkü entitlements bloğunuz onu zaten bildirir ve entitlements bloğu olmadan onu içe aktaran bir arka uç aynı geçitten geçemez. frontend, basePath, mountPath ve framework öğelerini tutar. nexus ise minVersion, maxVersion, capabilities[] ve permissions[] öğelerini tutar.

Kalan blokların her biri tek bir iş için oradadır:

Blok Amacı
settings Paylaşılan çerçevedeki ayarlarınız: her birinin belirttiği düzeylerde ayarlanan groups ve keys
people sweep (service, port): kimlik servisinden eşitlenen, biri ayrıldığında koltukları kapatılan kuruluş üyeleri
ontology entityTypes ve relationshipTypes: kendi şemanızda tutulan tipli graf
release groups ve frame: rotalarınızın aşamalandırıldığı, ilk olarak kanarya (canary) sürümü şeklinde yayınlanan yetenek grupları
cells[] Birden fazla dağıtılabilir birimden oluşan bir eklenti: her biri için name, kind, entrypoint, port, wsPort
pricing Katalog listelemeniz için model, currency, tiers[]
marketplace category, icon, screenshots, documentation, featured
compliance instruments[], dataResidency, sovereignty
developer, repository, keywords Onu kimin yayınladığı ve kodunun nerede barındığı
metrics, atlas Kendi metrik adlarınız ve mimari belgesi üretiminiz için bilinçli olarak açık bırakılmış iki nesne

Şemanın söyleyemedikleri

JSON Şeması şekli belirler; definePlugin ise bir şemanın ifade edemeyeceği kuralları ekler. Bir becerinin classification değeri güven tavanını aşamaz. Yalnızca core ve verified eklentileri tool_using ve llm_only becerilerini bildirebilir. Bildirilen her yol göreli ve aynı kökenli (same-origin) olmalı, şema, // ve ters eğik çizgi içermemelidir; çünkü URL ayrıştırıcısı \ öğesini / öğesine dönüştürür ve /\evil.example/x çapraz kökenli (cross-origin) olarak çözümlenir. Kayıt defteri eşitlemesinin bir beceriye uyguladığı her kural, eşitlemenin kendi koduyla önce burada uygulanır; böylece validate ve eşitleme, ihlal edilen bir kuralı aynı şekilde adlandırır.

Doğrulama ve v1'den geçiş

npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json
✔ anomaly-review@0.3.0 · tier=full-service · trust=community · skills=1 · mcpTools=0

Bir hata durumunda önce tam yol ve bir eşitleme kuralı söz konusuysa kod yazdırılır. Bunu bir commit kancası (hook) haline getirin.

Bir v1 bildirimi mekanik olarak yükseltilir. migrate üç yasa cümlesini ekler, domain öğesini domains[] öğesine taşır ve sahip olmadığınız bir giriş noktası uydurmayı reddeder. Herhangi bir şey yazdırmadan veya kaydetmeden önce sonucu doğrular; böylece bir taşıma işlemi asla araçtaki bir hatayı deponuza taşımaz.

npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --write

Depoya işlemeden önce farkları (diff) okuyun. Eklediği yasa cümleleri, doğrulayıcının sabitlediği ifadelerdir; kendi kurulumunuz için deploy öğesini daha önce gösterilen cümleye ayarlayın.

Kiracılığı (tenancy) oluşturma ve rolleri sağlama

Rol yetkilerinizi veya satır düzeyinde güvenlik şablonunu asla elle yazmazsınız. nexus-tenancy render bunları bildirimin schema ve db öğelerinden yazar:

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sql

Oluşturulan dosya, şema için her biri sahip olmaması gereken özelliklerle tanımlanmış beş rol yaratır: yalnızca sahip (owner) olabilen bir taşıyıcı (migrator), oturum açamayan bir sahip, istek yolu için bir uygulama rolü, yalnızca toplamları (aggregates) gören bir rapor rolü ve yalnızca ekleme yapabilen bir defter rolü. Hiçbir rol BYPASSRLS yetkisine sahip değildir. Bir kiracıyı bağlamanın tek yolu tek bir veritabanı işlevidir ve set_config yetkisi sahip dışındaki her rolden geri alınmıştır.

Uygulanmış bir çoklu kiracı (tenancy) dosyası asla düzenlenmez. Bir değişiklik, kendi 0 numaralı dosyasına sahip bir revizyondur ve kuruluşlar arası yetkilere yönelik okuma koltuğu 2. revizyon olarak bu şekilde gelir. --graph, ontology öğenizin bildirdiği tipli grafın iki tablosunu bir sonraki numaralandırılmış taşımanız olarak oluşturur.

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sql
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --graph --out migrations/001_graph.sql

Çoklu kiracı dosyası, çalıştırıcının bağlanırken kullandığı rolleri oluşturur; bu nedenle veritabanı sahibi tarafından nexus-migrate provision ile uygulanır:

DATABASE_URL=<database-owner-url> npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate provision --state <dir>

<database-owner-url> veritabanı sahibi için bir bağlantı dizesidir ve <dir> özel bir dizindir. Sağlama (provision) işlemi, temel çoklu kiracı dosyasını ve her revizyonu sırayla uygular, migrator.url ve app.url (ve 2. revizyon var olduğunda seat.url) dosyalarını 0600 moduyla <dir> içine yazar ve hiçbir gizli bilgiyi yazdırmaz. Her çalıştırmada db.maxConnections × db.pods üzerinden her rolün bağlantı sınırını ayarlar. Yeniden çalıştırma, siz istemediğiniz sürece mevcut parolaları korur: --passwords <dir> bunları dosyalardan ayarlar ve --rotate <roles> belirtilen rollere yeni parolalar verir. Bu dosyaları dağıtımınızın gizli bilgilerine (secrets) dönüştürün.

Bundan sonra uygulama işlemi, sağlama adımının yazdığı taşıyıcı bağlantı dizesiyle bağlanır:

DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.json

001 ve sonraki dosyaları taşıyıcı olarak, her dosya SET ROLE <schema>_owner altında ve dosya başına bir işlem (transaction) olacak şekilde çalıştırır. Her dosyanın sağlama toplamını (checksum) içeren <schema>.schema_migrations adlı bir defter tutar; baytları değişmiş uygulanmış bir dosya adıyla reddedilir (CHECKSUM_DRIFT), asla yeniden çalıştırılmaz ve asla atlanmaz. Bekleyen her dosya, daha ilki çalışmadan önce gerçek Postgres dilbilgisiyle ayrıştırılır, böylece bir ret durumunda veritabanı dokunulmadan kalır. Bir dosyanın taşıyabileceği tek başlık, isteğe bağlı kilit ve ifade zaman aşımlarıyla birlikte -- nexus-migration: transaction=file|per-statement başlığıdır; per-statement ise CREATE INDEX CONCURRENTLY içindir.

Geçitler

nexus-gates yirmi iki geçit çalıştırır. Her biri, iki kez gönderilememesi için bir kusur sınıfını kodlar ve her birinin, kendisini tetiklemek üzere oluşturulmuş bir düzenek (fixture) üzerinde başarısız olduğunu kanıtlayan bir iç testi vardır. Kodunuzu göndermeden (push) önce bunları çalıştırın:

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test
Geçit Yakaladığı durum
scope-adherence Kapsam koruması olmayan bir /api rotası; tam olarak bildirilmiş bir yol olmayan anonim bir yol; cihaz koruması olmayan veya yanında bir kişi koruması bulunan bir cihaz rotası
one-fence Elle yazılmış bir koltuk veya yetki çiti (fence) dahil olmak üzere, tek bir yer dışında herhangi bir yerde tanımlanmış bir kiracı yüklemi (predicate)
sql-fence Herhangi bir FROM, JOIN, USING veya UPDATE hedefinde, çit olmadan kapsamlı bir tabloyu okuyan veya güncelleyen bir ifade
migrations-are-scoped Bir ekseni, kiracı öncelikli bileşik anahtarı, kiracı taşıyan yabancı anahtarı veya demo sütunu eksik olan bir tablo
migrations-commit-what-they-open BEGIN sayısı COMMIT ve ROLLBACK sayısıyla eşleşmeyen bir taşıma
no-direct-compute Bir model sağlayıcısına, motora, kuyruğa veya iş akışı ana bilgisayarına doğrudan çağrı; yönlendirme URL'sinin ikinci bir okuyucusu
no-credentials Depoda veya ortamda okunabilir bir model sağlayıcısı kimlik bilgisi
crud-adherence Hak denetimi kayıtta hiçbir şeyi belirtmeyen, veri değiştiren (mutating) bir rota
blocked-backends Ne hizmet verilen, ne adıyla engellenen, ne yasayla reddedilen ne de başka bir yerde sahip olunan bir rota
every-test-runs Test betiğinin glob deseninin asla ulaşamadığı testler
tiles-are-invariant Bir kiracı değerini okuyan veya kimlik doğrulamasını atlayan, kiracıdan bağımsız önbelleğe alınmış bir birleşim yeri (seam)
api-contract Bildirimin beyan etmediği kayıtlı bir rota veya kodun asla kaydetmediği beyan edilmiş bir rota
rls-present Zorunlu satır düzeyinde güvenliği olmayan bir tablo; sabitlenmiş bir search_path değeri olmayan bir SECURITY DEFINER işlevi
no-set-config Kiracı ayarını kendisi bağlayan eklenti kodu
db-role-honest Sahip veya taşıyıcı olarak bağlanan ya da SUPERUSER veya BYPASSRLS isteyen bir istek yolu
platform-clients İçe aktarılmış ancak backend.platformClients içinde listelenmemiş veya listelenmiş ancak asla içe aktarılmamış bir SDK istemcisi
rights-register Bildirilmiş bir hakkı olmayan bir kapsam rotası; kaydın dışında bir hak denetimi
refusal-ledger Kurulu bir defteri olmayan bildirilmiş bir ret tablosu veya bunun etrafından dolaşılarak gönderilen bir ret gövdesi
grants-declared Bildirimin beyan etmediği yetkilendirilmiş bir tablo; elle dağıtılmış okuma koltuğu ayrıcalıkları
people-declared Tarama (sweep) rotası, koruması ve tabloları olmayan bir people bloğu
functions-closure Hizmet verilen rotaları ile bildirilen rotaları uyuşmayan bir Azure Functions eklentisi
declared-input Rotanın bildirdiği query ile eşleşmeyen bir işleyici sorgu parametresi listesi

gates/ dizini, bir geçidin okuyabileceği beş muafiyet dosyasını (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json ve invariant-seams.json) kayıt başına bir neden olacak şekilde tutar. Boş bir neden kayıt yokmuş gibi sayılır ve artık var olmayan bir şeyi belirten bir kayıt geçidin başarısız olmasına neden olur. Ayrıca kendi geçit modüllerinizi de oraya bırakabilirsiniz; nexus-gates bunları yerleşik olanların yanında alır.

Uyumluluk
Uyumluluk
Uyumluluk, hızlı başlangıç kılavuzunun her gece yapılan çalıştırmalarından elde edilen verilerle hangi SDK sürümünün hangi platform sürümüyle çalıştığını gösterir. Test edilmemiş bir çift bunu belirtir ve başarısız olan bir çift ise onu bozan değişikliği adlandırır.

Şablonun iş hattı (pipeline)

Şablon, elle yazılmış hiçbir iş akışı barındırmaz. İşlem hattı yapılandırması Dockerfile dosyasını, tek derleme argümanını (kayıt defteri belirteci), taşıma prova çalıştırmasını, başlatma yoklamasını (boot probe) ve birleştirme kuyruğunun (merge queue) çalıştırdığı geçidi belirtir. Sıralama, başarısız olmasını isteyeceğiniz sıralamadır.

  1. npm ci
  2. npm run typecheck
  3. npm run build
  4. npm test
  5. npm run validate:manifest, yani create-nexus-plugin validate nexus.manifest.json
  6. npm run gates, yani nexus-gates --self-test
  7. node scripts/ci/required-env

İmaj etrafında iki kontrol daha çalışır. Taşıma deneme çalışması (migration dry run), imaj yayınlanabilmeden önce canlı ortamın kullandığı aynı çalıştırıcıyla her dosyayı geçici bir Postgres'e uygular: önce süper kullanıcı olarak bir kez nexus-migrate provision, ardından taşıyıcı (migrator) olarak numaralandırılmış her dosya. Önyükleme yoklaması (boot probe), derlenmiş imajı kendi giriş noktasıyla ve required-env tarafından yazdırılan her değişkenle, bağlantıları kabul eden ancak hiç yanıt vermeyen yedek hedeflere yönlendirilmiş olarak başlatır. Sunucu, sınırlı zaman aralığı içinde veritabanını bekler ve bu bekleyiş geçiş sinyalidir; önyüklemeyi reddeden bir yapılandırma yükleyicisi, derlemeyi canlı ortamda değil orada başarısız kılar.

Community üzerinde geliştirme
Community üzerinde geliştirme
Community sürümünde bir geliştirici, kodu kendi Git barındırıcısında olmak üzere, tek bir sunucu üzerinde aynı altın yolları (golden paths), bir geliştirme alanını ve veri dallarını elde eder. Hazırlık (staging) ortamı, pilot birimler ve canlı verilerin maskelenmiş kopyaları Enterprise sürümüyle birlikte gelir.

Maliyeti nedir

SDK kararları sizin elinizden alır ve bunların bazılarını siz olsanız farklı verirdiniz. Bildirim dosyası (manifest) tanımadığı anahtarları reddeder, yönlendirme tablosu kodunuzla birebir eşleşmek zorundadır, veritabanı rollerini tasarlamak size ait değildir ve geçitler bir okuma işlemindeki eksik yetki nedeniyle derlemeyi başarısız kılar. İlk eklentimde, kaydettiğim ancak beyan etmeyi unuttuğum bir yönlendirme hakkında api-contract ile tartışarak bir gün geçirdim. Haklıydı; yönlendirme korumasızdı. İlk eklentinin yavaş ilerlemesini, ikincisinin ise üçte biri kadar zaman almasını bekleyin.