SQL RPC ve Idempotency

SQL/RPC, transaction ve idempotency

English · Türkçe · Languages / Diller

Kapsam: JSON API Forge 0.5.1 · İnceleme: 17 Eylül 2026 · Dil: Türkçe

Operation, önceden tanımlı bir veya daha fazla SQL statement'ının adlandırılmış HTTP işlemidir. Varsayılan method POST, path rpc/<name>, database primary, transaction true olur. En az bir statement ve özel işlem için permission gerekir. Public işlem açık public=true ister.

Statement modeli

Alan	Anlam
sql	Güvenilir işletmecinin yazdığı sabit SQL
params	Bind parametresi → değer kaynağı
mode	execute, fetch_one, fetch_all, scalar
result_name	Sonucun operation çıktısındaki adı
max_rows	Sınırlı sonuç; varsayılan 1000
require_rowcount_min/max	Beklenmeyen etki sayısında işlemi reddetme

Kaynak değerler $body.*, $path.*, $query.*, $header.*, $param.*, $principal.* ve uygun durumda $request.id olabilir. $param önceden doğrulanan parametre bağlamıdır. Kullanıcı değerini SQL string'ine birleştirmeyin; tablo/sütun adını body'den doğrudan SQL'e çevirmeyin.

Atomiklik

Transaction içindeki bir statement başarısız olduğunda aynı veritabanındaki önceki adımlar geri alınır. Örneğin transferde "bakiye yeterliyse düşür → karşı tarafa ekle → ledger kaydı" aynı transaction'a konur. Yetersiz bakiyede UPDATE'in etkilenen satır sayısı 0 olur; rowcount guard işlemi durdurur.

transaction=false yalnız açık SELECT/SHOW/EXPLAIN gibi read-only kullanım içindir. Execute statement ile birleştirilemez. allow_ddl ayrı açık seçenektir; güvenilir yapılandırmanın yanlış kullanımını azaltır, saldırgan SQL'i çalıştırmak için sandbox sağlamaz.

Idempotency sözleşmesi

idempotency=true ise:

• transaction=true zorunludur.
• Varsayılan Idempotency-Key başlığı gerekir; server 1–200 karakter sınırı uygular.
• Kimlik proje + operation + principal türü/subject + anahtardan türetilir.
• Gövde, path/query, doğrulanmış parametreler, tenant ve başvurulan header'lardan fingerprint hesaplanır.
• Aynı kimlik + aynı giriş, saklanan başarılı sonucu tekrar oynatır.
• Aynı anahtar + değişen giriş 409 conflict üretir.
• Ledger, SQL yan etkileri ve sonuç aynı iş DB transaction'ında commit edilir.

İlk çalıştırma sonrası network cevabı kaybolursa aynı anahtar ve aynı payload ile tekrar denenebilir. İşlemin sonucu belirsizken yeni anahtar üretmek ikinci yan etki yaratabilir. Anahtarı kullanıcı eylemi/iş komutu için oluşturun ve izin verilen retry süresi boyunca koruyun.

Replay X-Forge-Idempotent-Replay: true ve nesne gövdesinde _idempotent_replay: true işaretlerini kullanır. Cache invalidation ve background hook'lar replay'de tekrar çalıştırılmaz. Varsayılan TTL 86400 saniyedir; TTL sonrasında aynı anahtar yeni işlem olarak değerlendirilebilir.

Cache ile ilişkisi

Operation cache yalnız GET ve read-only statement'lar içindir. Idempotent operation ile response cache aynı anda etkinleştirilemez. Principal'a bağlı SQL'de vary_by_principal=false kabul edilmez. Cache/idempotency işleminde $request.id bağlamak uygun değildir ve doğrulamada reddedilir.

Mutation sonrası invalidate_resources resource path değerlerini, invalidate_operations operation name değerlerini kullanır. Başarılı ilk çalıştırmada invalidation olur; retry replay'inde tekrarlanmaz.

Sınırlar

Idempotency email, Discord isteği, ikinci veritabanı veya harici ödeme servisini aynı transaction'a katmaz. Harici etkiler için outbox/inbox veya sağlayıcının idempotency mekanizması gerekir. Cluster failover'da aynı ledger ve iş verisi paylaşılmıyorsa iki farklı sunucu aynı işi ayrı ayrı yapabilir.

Tam çalışan başlangıç örneği: İlk API. Daha kapsamlı örnek: exampleApps/app/GuildLedger. Tüm alanlar: İşlem modelleri.

Kaynak ve doğrulama

Bu sayfa aşağıdaki sabit commitlerdeki davranışı açıklar. Yeni bir sürümde aynı davranışın sürdüğünü varsaymayın.

• main/framework/operations.py
• main/framework/config.py
• main/framework/routers/project.py
• exampleApps/app/GuildLedger/config/50-operations.json

---

Wiki ana sayfa · Tüm sayfalar · Sürüm ve bakım