Nuvaka › Geliştirici belgeleri › Program uyumluluğu

Program uyumluluğu ve bağımlılıklar

Her program paketi nerede çalıştığını (compat), her sürüm de neye ihtiyaç duyduğunu (dependencies) bildirmek zorundadır. Bildirimler eksikse sürüm incelemeye gönderilemez. Mağaza bu bilgilerle kartta "Ubuntu 22.04+, Fedora 39+ · x86_64" gibi bir özet gösterir. Uygulama da cihaza uygun paketi seçer ve eksik bağımlılıkları kullanıcıya söyler.

Uyumluluk bildirimi (compat)#

compat paket başına, yani her platform anahtarı için ayrı verilir. İki yolu var:

• yüklerken ?compat= sorgu alanında, URL kodlu JSON olarak;
• sonradan PUT /api/programs/dev/{id}/versions/{v}/packages/{platform}/compat ile, gövdede JSON olarak.

Sunucu bildirimi doğrular ve normalize eder. Normalize bildirim paket kaydına girer ve imzalanır.

Biçim#

// Windows: windows-msi, windows-exe, windows-exe-arm64, windows-msix
{ "arch": "x86_64", "os": { "minVersion": "10.0.19041" },
  "launch": { "uninstallKey": "Nuvaka GPU Control", "exe": "bin\\GpuControl.exe" }, "processName": "GpuControl.exe" }

// macOS: macos-dmg
{ "arch": "universal", "os": { "minVersion": "12.0" }, "launch": { "bundleId": "com.nuvaka.gpucontrol" } }

// Android: android-apk
{ "arch": "universal", "os": { "minSdk": 26 } }

// Linux paket yöneticisi: linux-deb, linux-rpm, linux-pacman
{ "arch": "x86_64", "linux": { "distros": [ { "id": "ubuntu", "min": "22.04" }, { "id": "debian", "min": "12" } ] },
  "launch": { "desktopId": "gpu-control.desktop" }, "processName": "gpu-control" }

// AppImage: linux-appimage ("glibc 2.31 ya da üstü olan her dağıtım")
{ "arch": "x86_64", "linux": { "glibc": "2.31" }, "launch": { "desktopId": "gpu-control.desktop" } }

Bilinmeyen alan reddedilir. Linux anahtarlarında arch, linux, launch, processName, packageName, replaces, ui, bridge ve background; Windows ve macOS'ta arch, os, launch, processName, ui, bridge ve background; Android'de yalnız arch ve os olabilir. ui, bridge ve background yalnız masaüstü paketlerinde bulunur (Yerel uçlar). Eski minOsVersion alanı compat'tan türetilir: Windows ve macOS'ta minVersion, Android'de minSdk, Linux'ta boş.

Başlatma bilgisi (launch) ve süreç adı#

Masaüstü paketlerinde (Windows, macOS, Linux) launch zorunludur. Uygulama programı yalnız bu bilgiyle başlatır; bir uzantının verdiği yolu asla kullanmaz.

processName isteğe bağlıdır: programın "çalışıyor" durumu için süreç adı (yol değil), ör. GpuControl.exe ya da gpu-control. İkisi de compat'ın parçasıdır; imzalı paket kaydına girer ve detayda packages[].compat içinde döner. Hata yolları: compat.launch, compat.launch.exe, compat.processName gibi.

Dağıtım aileleri#

Ailesine uymayan bir dağıtım yazarsan reddedilir. Ör. bir deb paketinde fedora yazarsan yanıt şöyle olur:

{ "success": false, "error": "compat_invalid", "path": "compat.linux.distros[1].id",
  "message": "fedora bu paket türüne uymaz; linux-deb için: debian, ubuntu, linuxmint, …" }

Örnek: tek sürümde beş paket#

Kısalık için launch alanları yazılmadı; her masaüstü paketinde gerekir.

// windows-msi
{ "arch": "x86_64", "os": { "minVersion": "10.0.19041" } }
// windows-exe-arm64 (arch kendiliğinden arm64)
{ "os": { "minVersion": "10.0.22000" } }
// linux-deb
{ "arch": "x86_64", "linux": { "distros": [ { "id": "ubuntu", "min": "22.04" }, { "id": "debian", "min": "12" }, { "id": "linuxmint", "min": "21" } ] } }
// linux-rpm
{ "arch": "x86_64", "linux": { "distros": [ { "id": "fedora", "min": "39" }, { "id": "opensuse-tumbleweed" } ] } }
// linux-pacman
{ "arch": "x86_64", "linux": { "distros": [ { "id": "arch" }, { "id": "manjaro" }, { "id": "endeavouros" } ] } }

Yerel uçlar: ui, bridge, background#

Programın arayüzü ve widget'ı uygulamaya yerel uçlarla bağlanır. Uçlar paket başına compat içinde bildirilir: imzalı paket kaydının parçasıdır ve yolları işletim sistemine göre değişir. Yalnız masaüstü paketlerinde (Windows, macOS, Linux) bulunur; Android'de bu alanlar bilinmeyen alan sayılır ve reddedilir.

• ui: programın Nuvaka penceresinde açılan arayüzü. runMode:"embedded" programlarda her masaüstü paketinde zorunludur.
• bridge: eşlikçi uzantının widget'ının programla konuştuğu köprü. widget.kind:"extension" sürümlerde her masaüstü paketinde zorunludur.
• background: uygulamanın, kullanıcı onayıyla başlatabileceği arka plan parçası.

Gömülü arayüz (ui)#

// önerilen: unix soket ya da named pipe (port gaspı yok, belirteç gerekmez)
"ui": { "transport": "unix", "path": "runtime:gpu-control-ui.sock", "args": ["--serve"] }          // Linux, macOS
"ui": { "transport": "pipe", "pipe": "\\\\.\\pipe\\nuvaka-gpu-control-ui", "args": ["--serve"] }  // Windows
// http: belirteç dosyası (handshake "file"; portFile ile varsayılan)
"ui": { "transport": "http", "portFile": "gpu-control-ui.json" }
// http: ortam değişkeniyle el sıkışma (UI sunucusunu uygulama başlatır)
"ui": { "transport": "http", "port": 47123, "handshake": "env", "args": ["--serve"], "urlPath": "/app" }

Kullanıcı çalışma dizini. runtime: yolları ve portFile bu dizine göre çözülür:

• Linux: $XDG_RUNTIME_DIR (yoksa /run/user/<uid>);
• Windows: %LOCALAPPDATA%\Nuvaka\run;
• macOS: $TMPDIR (getconf DARWIN_USER_TEMP_DIR).

Uygulama bu kökün dışına çıkan yolu (sembolik bağ dahil) reddeder.

http el sıkışması (zorunlu). Port gaspına ve DNS rebinding'e karşı korur:

• handshake:"file": programın kendi kullanıcı düzeyindeki UI sunucusu (asla root servis değil) portFile'ı 0600 kipinde yazar: { "port": 47123, "token": "<en az 32 bayt rastgele, base64url>" }. Uygulama dosyanın sahibinin kullanıcı olduğunu ve grup ya da diğerlerine açık olmadığını denetler.
• handshake:"env": UI sunucusunu uygulama kendisi başlatır (args ile) ve ortama NUVAKA_UI_TOKEN=<rastgele> koyar. Görünüm açılmadan önce GET http://127.0.0.1:<port>/.well-known/nuvaka-ui isteği (yetkisiz) { "token": "<NUVAKA_UI_TOKEN>" } döndürmelidir; tutmazsa hiçbir şey gösterilmez. portFile ile birlikte kullanılırsa dosya yalnız { "port" } içerebilir.
• İki kipte de uygulama istekleri kendi özel şeması üzerinden vekil olarak iletir: Host: 127.0.0.1:<port> ve Authorization: Bearer <token> ile. Belirteç görünüme (webview) asla ulaşmaz. Programın sunucusu başka bir Host değerini ve belirteçsiz isteği reddetmeli (401 ya da 421) ve yalnız 127.0.0.1'e bağlanmalı.
• unix soket ve pipe'ta belirteç yoktur; bunun yerine uç sahipliği denetlenir (aşağıda).

Widget köprüsü (bridge)#

// Linux: sistem servisi (gpud)
"bridge": { "source": "service", "transport": "unix", "path": "/run/nuvaka-gpud/gpud.sock", "protocol": "jsonl-v1",
            "hello": { "cmd": "hello", "proto_version": 1 },
            "methods": [ { "name": "status", "readOnly": true }, { "name": "set_profile", "readOnly": false, "rateLimitPerMin": 30 } ] }
// Windows
"bridge": { "source": "service", "transport": "pipe", "pipe": "\\\\.\\pipe\\nuvaka-gpud", "protocol": "jsonl-v1", "methods": [ … ] }
// arka plan parçası ve kullanıcı soketi
"background": { "args": ["--background"] },
"bridge": { "source": "background", "transport": "unix", "path": "runtime:gpu-control.sock", "protocol": "jsonl-v1", "methods": [ … ] }

Köprü sözleşmesi (jsonl-v1) ve uygulamanın sınırları#

Uzantı köprüyü nuvaka.programs.call(method, params?) ile çağırır; sonuç bir Promise'tir. Çağrı yalnız companionOf değeri ve programs: "companion" izni olan, programın kurulu sürüm kaydında widget.kind:"extension" ve widget.extensionId değeri kendisi olan uzantıda çalışır (Ana sayfa widget'ı). İsteği uygulama kendisi kurar; uzantı ham satır gönderemez.

Çerçeve: UTF-8, satır başına bir JSON nesnesi, satır \n ile biter (satır içinde ham yeni satır olmaz). Bir bağlantıdaki istekler sıralıdır; her istek satırına bir yanıt satırı gelir.

→ {"cmd":"hello","proto_version":1}                       // hello varsa, bağlantının ilk satırı (aynen)
← {"ok":true}
→ {"id":1,"method":"status","params":{}}
← {"id":1,"result":{"temp":61,"profile":"quiet"}}
→ {"id":2,"method":"set_profile","params":{"name":"perf"}}
← {"id":2,"error":{"code":"busy","message":"…"}}

• http'de (yalnız source:"background"): her istek satırı POST /.well-known/nuvaka-bridge isteğinin gövdesidir; yanıt gövdesi tek satırdır. El sıkışma ve Host/Bearer kuralları ui'daki gibidir.
• Sınırlar: params en çok 64 KB, yanıt satırı en çok 1 MB, yanıt zaman aşımı 5 sn. rateLimitPerMin yöntem başına, uygulamada uygulanır.
• Yazma yöntemleri (readOnly:false) yalnız kullanıcı hareketinden (tıklama ya da tuş, yaklaşık 1 sn içinde) sonra çağrılabilir; aksi hâlde gesture_required.
• Uç sahipliği: unix soketin sahibi root ya da kullanıcı olmalı ve soket herkese yazılabilir olmamalı (runtime: soketleri kullanıcıya aittir; 0600 önerilir). Windows'ta pipe sunucusunun süreci (GetNamedPipeServerProcessId) programın InstallLocation dizini altındaki bir dosya olmalı. Tutmazsa uygulama bağlanmaz (bridge_unavailable).

Hatalar Promise reddi olarak gelir; kod error.code alanındadır:

Programın kendi döndürdüğü hata kodu (ör. busy) error.code'da aynen gelir; önüne ek konmaz.

Arka plan parçası (background)#

"background": { "args": ["--background"], "persist": false }

• args: 1–16 metin (her biri en çok 256 karakter, NUL yok). persist: isteğe bağlı bool, varsayılan false.
• Uygulama yalnız compat.launch hedefini bu argümanlarla başlatır: Linux'ta .desktop dosyasının Exec satırı (alan kodları atılır), Windows'ta InstallLocation\exe, macOS'ta bundleId. Bunu root ya da yönetici yetkisi olmadan ve kullanıcının açık onayından sonra yapar ("GPU Control arka planda çalışsın mı?"); kullanıcı onayı ayarlardan geri alabilir.
• Arka plan parçası Nuvaka açılınca başlatılır, Nuvaka kapanınca durdurulur. persist:true ise çalışmaya devam eder.

Bağımlılıklar (dependencies)#

dependencies sürüm başına verilir: POST …/versions ile sürümü oluştururken ya da sonradan PUT …/versions/{v} ile. Alan zorunludur. Bağımlılık yoksa boş liste [] gönder; bu açıkça "bağımlılık yok" demektir. Alanı hiç göndermezsen sürüm incelemeye gönderilemez (dependencies_required).

[
  { "kind": "driver", "name": "NVIDIA driver", "version": ">=535", "required": false, "platforms": ["windows", "linux"],
    "note": { "tr": "Yalnız NVIDIA ekran kartlarında", "en": "NVIDIA GPUs only" }, "url": "https://www.nvidia.com/drivers" },
  { "kind": "hardware", "name": "NVIDIA or AMD GPU", "required": true },
  { "kind": "runtime", "name": ".NET Desktop Runtime", "version": ">=8.0", "required": true, "platforms": ["windows"],
    "url": "https://dotnet.microsoft.com/download/dotnet/8.0" },
  { "kind": "program", "name": "nuvaka.gpu-runtime", "version": ">=1.0.0", "required": true }
]

• En çok 30 bağımlılık olabilir. Aynı kind ve name ikilisi iki kez yazılamaz. Bilinmeyen alan reddedilir.
• Linux sistem kütüphanelerini burada değil, paketin kendi bağımlılık alanında bildir (Depends:, Requires:, depends=()). Onları paket yöneticisi kurar. Bu liste paket yöneticisinin kuramayacağı şeyler içindir.
• program bağımlılığında uygulama, kullanıcıya önce o programı kurmayı önerir. O programın paketi de kendi compat bildirimine göre seçilir. Bağımlı olunan program sonradan yayından kalkarsa yeni sürümün gönderimi ve onayı reddedilir.

Hata kodları#

Mağaza ve uygulama ne görür#

Liste kartında (GET /api/programs) son sürümün paketlerinden işletim sistemi başına bir özet bulunur:

"compat": {
  "windows": { "arch": ["x86_64", "arm64"], "minVersion": "10.0.19041" },
  "linux":   { "arch": ["x86_64"], "distros": [ { "id": "ubuntu", "min": "22.04" }, { "id": "fedora", "min": "39" } ], "glibc": "2.31", "anyDistro": true },
  "android": { "arch": ["universal"], "minSdk": 26 }
}

Değerler paketler arasındaki en düşük sürümlerdir. anyDistro: true, bir AppImage paketi olduğunu, yani glibc yeterliyse her dağıtımda çalıştığını gösterir. Detayda (GET /api/programs/{id}) her paketin tam compat'ı, her sürümün dependencies'i ve son sürümün bağımlılıkları bulunur. Program bağımlılıklarına mağaza kartı eklenir.

Eşleştirme kuralları#

Uygulama kararı cihazda kendisi verebilir. İstersen sunucuya da sorabilirsin: detay isteğine cihaz bilgisini eklersen yanıtta compatibility alanı gelir.

GET /api/programs/{id}?platform=linux&arch=x86_64&distro=ubuntu&distroVersion=24.04&distroLike=debian&glibc=2.39

"compatibility": {
  "compatible": true, "recommended": "linux-deb",
  "packages": [
    { "platform": "linux-appimage", "compatible": true,  "reasons": [], "warnings": [] },
    { "platform": "linux-deb",      "compatible": true,  "reasons": [], "warnings": [] },
    { "platform": "linux-rpm",      "compatible": false, "reasons": ["distro_not_supported"], "warnings": [] }
  ]
}

Parametreler:

• arch: x86_64 (amd64 ve x64 da olur) ya da arm64 (aarch64 da olur).
• osVersion: Windows'ta yapı numarası (10.0.22631), macOS'ta sürüm (14.5), Android'de API düzeyi (34).
• distro, distroVersion, distroLike: /etc/os-release dosyasındaki ID, VERSION_ID ve ID_LIKE değerleri.
• glibc: cihazın glibc sürümü.

Verilmeyen bilgi denetlenmez. Kurallar her paket için ayrı uygulanır:

• Mimari: universal paket her mimaride çalışır. Aynı mimari uyar. arm64 Windows ve Apple Silicon Mac, x86_64 paketi öykünmeyle çalıştırır: paket uyar, uyarı olarak arch_emulated eklenir. Diğer farklar arch_mismatch sebebiyle uymaz.
• Windows ve macOS: cihaz sürümü minVersion'dan küçükse os_too_old. Sürümler noktalı sayı olarak parça parça karşılaştırılır.
• Android: API düzeyi minSdk'dan küçükse os_too_old.
• glibc: cihazın glibc'si paketin bildirdiğinden eskiyse glibc_too_old.
• deb, rpm, pacman:
  • Dağıtım listede varsa ve min bildirilmişse cihazın sürümü en az min olmalı; değilse distro_too_old. Sürüm bilinmiyorsa uyarı distro_version_unknown eklenir.
  • Dağıtım listede yok, ama kendisi ya da ID_LIKE değerlerinden biri paketin ailesindeyse paket uyar ve uyarı distro_family_match eklenir. Bu durumda sürüm denetlenmez. Örnek: listede yalnız ubuntu varken Linux Mint.
  • Hiçbiri tutmazsa distro_not_supported.
• AppImage: dağıtıma bakılmaz; yalnız mimari ve glibc denetlenir.

recommended, uyan paketler arasından şöyle seçilir: tam eşleşme önce gelir; aile eşleşmesi ya da öykünme ikinci sıradadır; AppImage en son. Eşitlikte platform anahtarı listesindeki sıra geçerlidir. Hiçbir paket uymuyorsa compatible false, recommended null olur.

Nuvaka Apps API v1 · son güncelleme 2026-10-17