İçeriğe geç
zeev1.0.0-rc.1

ADR-034 — Kalıcı ortak web deposu ve tek-worker süreç modeli

Depodaki adr/034-web-ortak-depo-ve-worker-modeli.md belgesinden Zee ile üretildi.

  • Durum: kabul
  • Tarih: 2 Eylül 2026
  • Revizyon: 2 Eylül 2026 — K-139/ADR-036 kanonik origin ve açık loopback bind+peer değişmezini ekledi.
  • Revizyon: 21 Kasım 2026 — K-353: kilit dışı okuma + 128 denemeli CAS döngüsü kaldırıldı; durum yazma kilidi altında okunup yayımlanır.
  • Revizyon: 21 Kasım 2026 — K-360: paylaşılan dinleyicili işçi (grup, native profil) kabul ile SIGTERM denetimi arasına düşen bağlantıyı yanıtlar; ayrıntı ADR-161 eki.
  • İlgili kayıt: K-137, K-139, B-046, B-052, RFC-0017, ADR-018, V1-P0-03

Bağlam

ADR-018 process içi oturumları 4096 toplam/1024 anonim kayıtla sınırladı; K-134 oturum ve çerez mutation'ını HTTP yanıt transaction'ına aldı. Buna karşın process A'da açılan oturum process B'de görünmüyor, restart'ta kayboluyor ve revoke worker'lar arasında yayılmıyordu. Endpoint, CSRF ve özellikle CPU-pahalı Argon2id doğrulaması ortak atomik oran sınırı taşımıyordu.

Stage 0 HTTP sunucusu bir bağlantıyı kabul edip request'i okur, programı çalıştırır, yanıtı tamamlar ve ancak sonra yeni bağlantı kabul eder. Bu gerçeklik gizlenerek thread-pool sözü verilemez.

Karar

Oturum runtime'ı saklama ayrıntısından Depo sınırıyla ayrılır. Sınır; oturumu okuma, istek sonundaki ekle/sil mutation'ını atomik uygulama/geri alma, süre dolumunu temizleme ve rate-limit sayacını artırma işlemlerini sunar. Runtime doğrudan HashMap bilmez.

İki adaptör vardır:

  1. Deneysel/öğretici web için süreç içinde kilitli bellek deposu.
  2. --web-proxy production profili için proje kökündeki .zee/web-durumu-v1.json kalıcı ortak deposu.

Kalıcı adaptör her değişikliği süreçler arası dosya kilidi ve atomik replace ile yayımlar. K-353'ten beri durum aynı kilit penceresinde okunur, dönüştürülür ve yayımlanır; ilerlemeyi ADR-075 kilit kuyruğu sırası verir, tek sınır spec/08 5 sn kilit beklemesidir (aşılırsa 503). İlk sürüm durumu kilit dışında okuyup kilit altında eski byte'larla karşılaştırıyor (CAS), çakışmada yeniden okuyup 128 ardışık çakışmadan sonra isteği 503 ile reddediyordu: çok işçide yavaş süreç (yeniden başlatmada yeni açılan işçi, büyümüş depo) her turu kaybedebiliyordu (K-343 ölçümünde 1117 istekte bir 503). Bozuk JSON, bilinmeyen biçim sürümü, symlink, kayıt/alan sınırı veya IO hatası 503'tür. Unix'te .zee 0700, durum dosyası 0600'dür. Oturum belirtecinin yalnız SHA-256 özeti saklanır.

Oturum mutation'ı yanıt öncesi ortak depoya commit edilir. Socket yazımı başarısızsa yalnız bu commit'in değiştirdiği kayıtlar beklenen yeni değerleri taşıyorsa atomik geri alınır; başka süreçlerin ilgisiz kayıtları ezilmez.

Production oran profili kanonik istemci kimliğiyle şu sabit pencereleri uygular:

  • yöntem + sorgusuz path uç noktası: 60 saniyede 100 istek;
  • CSRF doğrulaması: 60 saniyede 60 deneme;
  • Argon2id parola doğrulaması: 300 saniyede 5 deneme.

Sayaç artışı ve pencere sonu aynı kilitli ortak depo transaction'ındadır. Altıncı parola doğrulaması Argon2id çalıştırılmadan 429 olur. En çok 32768 canlı oran anahtarı tutulur; süresi dolanlar temizlenir, yalnız canlı kayıtlarla doluluk yeni kimliği tahliye ederek eşiği delmek yerine fail-closed reddeder.

--web-proxy yalnız loopback proxy'ye güvenir. Proxy, istemciden gelen bütün proxy başlıklarını silip tam bir Forwarded: for=<IP>;proto=https;host=<host> başlığı kurar. Runtime tek header/tek halka ister, IP'yi IpAddr ile kanonikler ve X-Forwarded-Forı kimlik kaynağı saymaz. K-139'da listener açıkça 127.0.0.1e bind edilir ve kabul edilen peer ayrıca loopback olarak doğrulanır. CLI origin'i, Host, Forwarded host ve unsafe Origin, outbound allowlist ile aynı AgHedefi parser'ından geçip kanonik kimlikle karşılaştırılır.

V1 server modeli bilinçli olarak tek worker/thread per processtir. Concurrency, reverse proxy arkasında aynı proje kökünü/deposunu paylaşan N ayrı dil süreciyle kurulur. Aynı kaynak dosyası her süreçte farklı loopback porta --web-worker-port N ile bağlanır. Thread-pool veya aynı process içinde eşzamanlı Zee request yürütümü V1 sözü değildir.

Reddedilen seçenekler

  • Sticky session: restart/revoke/rate-limit ortaklığını sağlamaz.
  • İstemci rolü/JWT: anlık revoke ve anahtar yönetimi karmaşasını istemciye taşır.
  • Hemen thread-pool: Zee runtime'ın gözlenebilir IO ve transaction determinizmini büyütür; V1 için N süreç daha dar ve denetlenebilir sınırdır.
  • Zorunlu Redis/harici servis: bootstrap dağıtımını üçüncü bir servise bağlar. Çok-hostlu deployment ileride aynı depo sözleşmesinin ayrı adaptörü olabilir; mevcut garanti aynı güvenilir dosya sistemini paylaşan süreçlerdir.

Sonuçlar

  • Login, revoke, expiry ve rate-limit restart ile worker geçişinde korunur.
  • Tek bağlantı bir worker'ı en çok mevcut request deadline'ları kadar meşgul edebilir; kapasite N process ve reverse-proxy buffering/timeout ayarıyla büyütülür.
  • Operatör, loopback dışı bind'e izin veremez; Forwarded başlığını dış istemciden aynen geçiremez. Loopback dışı socket peer'i doğru görünen başlıklarla dahi güvenilir proxy sayılmaz.
  • Gerçek iki CLI süreci; login, çapraz authenticated GET, restart, çapraz logout ve ortak 429 akışını uçtan uca doğrular. On paralel depo kullanıcısı 100 artışta eşik üstü tek isteğin kaçmadığını ayrıca kanıtlar.

Kaynak: adr/034-web-ortak-depo-ve-worker-modeli.md · Bütün belgeler