ADR-003: Değişiklik Tespiti için Blocking Query
Durum
Kabul edildi (2026-04-04)
Bağlam
KV değişikliklerini yakın-gerçek-zamanlı olarak tespit etmemiz gerekiyor. Consul üç mekanizma sunuyor:
- Blocking Query (long-polling): İstek yapılır, değişiklik olana kadar bağlantı açık kalır
- Events API (gossip-tabanlı): Gossip protokolü üzerinden olay dağıtımı
- Periyodik polling: Belirli aralıklarla istek gönderme
Karar
Consul Blocking Query birincil değişiklik tespit mekanizması olarak kullanılacak.
Sonuçlar
Olumlu
- Yakın-gerçek-zamanlı tespit: Tipik değişiklik algılama süresi 5 saniyenin altında
- Raft consensus üzerine kurulu: Tutarlı ve güvenilir, liderin onayladığı değişiklikler
- Resmi ve iyi dokümante edilmiş API: Consul'un desteklenen, stabil özelliği
- Streaming backend (Consul 1.10+): Bağlantı yeniden kurma yükünü azaltır
- ModifyIndex: Her key için verimli değişiklik takibi, gereksiz veri transferi yok
Olumsuz
- Açık bağlantı tutar: Consul server'da kaynak kullanımı (her prefix için bir bağlantı)
- Index geri gidebilir: Raft snapshot restore sonrası index sıfırlanabilir (özel durum yönetimi gerekir)
- Cevap değişiklik garantisi vermez: Idempotent yazma veya timeout'ta da cevap gelir, diff yapmak gerekir
- Max 10 dakika bekleme süresi: Timeout'ta yeniden bağlantı gerekir
Değerlendirilen Alternatifler
| Alternatif | Avantaj | Dezavantaj | Neden seçilmedi |
|---|---|---|---|
| Events API | Push-tabanlı, düşük gecikme | Teslim garantisi yok, kalıcı değil, global sıralama yok | Güvenilirlik yetersiz |
| Periyodik polling | Çok basit implementasyon | Yüksek gecikme, Consul'a gereksiz yük | Verimsiz, yavaş |
| consul watch CLI | Harici process, kolay başlangıç | Entegrasyon zor, az kontrol | Programatik kontrol yok |
Teknik Detay
Blocking query şu şekilde çalışır:
GET /v1/kv/config/?recurse&index=42&wait=5m
- index=42: "Bu index'ten sonraki değişiklikleri bekle"
- wait=5m: "En fazla 5 dakika bekle, sonra boş cevap dön"
Consul, belirtilen index'ten yüksek bir değişiklik olduğunda hemen cevap verir. Değişiklik olmadan bekleme süresi dolursa, aynı index ile boş cevap döner. Bu durumda Guardian aynı isteği tekrar gönderir.
Index geri gitmesi (Raft snapshot restore sonrası) durumunda Guardian index'i sıfırlar ve tam senkronizasyon yapar. Bu edge case'in doğru ele alınması kritiktir.