Yeniden bağlanma ve limitler

Bu sayfa, realtime soketi koptuğunda durumun nasıl kurtarıldığını, ResyncRequired geldiğinde ne yapılacağını, boşta kapanma (4100) davranışını ve sunucunun uyguladığı limitleri anlatır. Mobil ya da dengesiz ağda oynanan bir oyun yazıyorsanız bu sayfayı baştan sona okuyun.

Kopma sonrası kurtarma

Soket her zaman kopabilir (ağ, dağıtım, yük dengeleyici). Open Play’de kurtarma yeni soketle yeniden katılma (re-join) ile yapılır; eski soketin durumu sunucuda yeniden kullanılmaz.

1. Yeni bilet al. Her bağlantı yeni bir bilet ister (tek kullanımlık, 30 sn); eski bilet yeniden kullanılamaz (protokol).
2. Authenticate, Ready. Yeni sessionEpoch gelir. Yeni soket aynı kaynağa yazmaya başladığında oyuncunun eski soketi artık yazar değildir: eski soketin girdileri Ack: Stale alır.
3. Her abonelik için yeniden Join.
   • Kalıcı (durable) akışlarda: son aldığınız cursor’ı Join.cursor olarak verin. Sunucu kaldığınız yerden DurableEvent’leri tekrar oynatır ve yeni bir DurableRecovery bariyeri yollar (snapshot boştur).
   • Geçici (ephemeral) durumda: cursor yoktur; Join taze bir Snapshot getirir. Gönderilmiş ama Ack almamış Input’lar tekrar oynatılmaz: sonucu belirsizdir, oyun mantığınız en son Snapshot’a göre devam etmelidir.
   • Kalıcı komutlarda (Command): Ack gelmeden kopan komutun sonucu belirsizdir. Aynı idempotencyKey ile yeniden gönderin ya da sonucu sorgulayın (eklentileri çağırma); yeni anahtar üretmeyin.
4. ResyncRequired gelirse (imleç yok, süresi dolmuş, başka oyuncuya ait, boşluklu ya da tekrar bütçesini aşmış) imleci atın ve cursor olmadan tekrar Join edin; bu taze bir anlık görüntü getirir. Aynı imleçle ısrar etmeyin.

İmleç (cursor) kuralları

• Opaktır ve oyuncuya bağlıdır; başka oyuncunun imleci kullanılamaz. İçeriğini ayrıştırmayın.
• Her DurableRecovery ve her DurableEvent yeni bir imleç taşır; en sonuncusunu saklayın.
• Tek kurtarmada en çok 256 kalıcı olay tekrar oynatılır; fazlası ResyncRequired ile taze anlık görüntüye çevrilir.
• İmleç ve teslimat saklama penceresi 24 saattir; ondan eski imleç ResyncRequired alır.
• coveredEventIds’deki olaylar taze anlık görüntüde zaten vardır; bunları ayrıca uygulamayın.

TypeScript SDK ne yapar

SDK bu akışı sizin yerinize yürütür (RealtimeClient, client.realtime):

Durum makinesi idle, ticketing, connecting, authenticating, ready, recovering, live, backoff, reauthRequired, upgradeRequired, idleClosed ve closed değerlerinden geçer. Önemli olanlar:

• recovering / backoff: SDK yeniden bağlanıyor; aboneliklerin imleçleri korunur.
• reauthRequired: bilet ya da kimlik reddedildi (AuthenticationFailed, 401/403). Oturumu yeniden kurun; SDK kendiliğinden sonsuz döngüye girmez.
• upgradeRequired: sunucu protokol sürümünü ya da çerçeveyi tanımadı (UnsupportedProtocol, 426). İstemciyi güncelleyin.
• Sunucu PayloadTooLarge ya da CapacityExceeded gönderirse SDK bunu geri basınç (backpressure) hatası olarak yüzeye çıkarır; bağlantı durumunu değiştirmez.

Not

Tamamlanmamış girdiler soket koptuğunda “belirsiz sonuçlu” olarak reddedilir ve yeniden bağlanınca otomatik tekrar gönderilmez. Sinyal (best-effort) mesajları da tekrar edilmez.

Boşta kapanma (4100)

Sunucu, girdi kabul eden (etkileşimli) bir aboneliği olan ve belirli süre oyuncu etkinliği göndermeyen soketi kapatır.

• Kapanış kodu 4100, neden idle_timeout. Tipli Error çerçevesi yoktur; yalnız WebSocket kapanış çerçevesi.
• Süre varsayılan 5 dakikadır ve operatör tarafından değiştirilebilir ya da kapatılabilir. Kontrol aralığı min(süre/4, 15 sn) olduğundan kapanış eşikten en çok bu kadar geç gelir.
• Menüde ya da oyun öncesinde (girdi kabul eden abonelik yokken) sayaç işlemez.
• Etkinlik sayılan şey eklentinin tanımıdır: girdi çerçevesi genellikle sayılır; uygulama Ping, Authenticate ve protokol düzeyi ping sayılmaz. Oyununuz duraklatılmış ekranda da bağlı kalacaksa eklentinin tanımladığı canlı tutma girdisini gönderin; duraklatma, garaj gibi ekranlarda canlı tutma girdisi göndermek AFK sayılmamasını sağlar.
• Açık bir soket oturumu yaşatmaz: oturum ömrü ancak oyuncu REST isteği yaptıkça uzar (güvenlik); sunucu soketteki oturumu 25 saniyede bir yeniden doğrular.
• Bu kapanışı bir hata olarak ele almayın: oyuncuya “Devam et” gösterin, onayında yeni bilet alıp yeniden bağlanın; imleçler sayesinde abonelikler kurtarılır.

SDK’da onIdleClose geri çağrısını verirseniz istemci idleClosed durumuna geçer ve kendiliğinden yeniden bağlanmaz; kullanıcı onayında connect() çağırın. Geri çağrıyı vermezseniz kapanış sıradan bir kopma gibi işlenir ve SDK kendisi yeniden bağlanır.

import { createPlayerClient, type PlayerClient } from "@ferdiunal/open-play-ts";

/**
 * Sunucu boşta kapanışında (`4100`, `idle_timeout`) SDK kendiliğinden yeniden bağlanmaz; oyuncuya "Devam et"
 * gösterin ve onayında `connect()` çağırın. Abonelikler imleçleriyle kurtarılır.
 */
export function createClientWithIdlePrompt(
  baseUrl: string,
  environmentId: string,
  showContinueButton: (onContinue: () => void) => void,
): PlayerClient {
  const client: PlayerClient = createPlayerClient({
    baseUrl,
    environmentId,
    realtime: {
      reconnectBaseMs: 250, // ilk yeniden bağlanma denemesi 250 ms (varsayılan 1000)
      onIdleClose: () => showContinueButton(() => void client.realtime.connect()),
    },
  });
  return client;
}

Limitler

Notlar:

• Çerçeve hızı bütçesi Input’la sınırlı değildir; alınan her metin çerçevesi ve protokol düzeyi Ping bir çerçeve sayılır (Pong sayılmaz). Dürüst bir istemci yaklaşık 30 ile 35 çerçeve/sn gönderir; 40/sn’nin altında kalın ve bir duraksamadan sonra biriken çerçeveleri toplu göndermeyin.
• Sayılar sunucu varsayılanlarıdır; operatör bazılarını (boşta süresi, bağlantı sınırları, çerçeve bütçesi) ortam yapılandırmasıyla değiştirebilir. Barındırılan bir Open Play kullanıyorsanız değerleri sağlayıcınıza sorun.
• Input hızı ayrıca modülün şema belgesindeki ratePerSecond ve burst değerleriyle tanımlıdır.

Sıkıştırma

• Sunucu permessage-deflate (RFC 7692) sıkıştırmasını destekler, yalnız istemci teklif ederse devreye girer. Tarayıcılar bunu kendiliğinden teklif eder; ayrı bir şey yapmanız gerekmez. Benzer JSON çerçevelerinde belirgin küçülme sağlar.
• Operatör sıkıştırmayı kapatabilir; kapalıysa soket sıkıştırmasız çalışır, protokol değişmez.
• Unity yerel (native) WebSocket istemcisinde sıkıştırma henüz yoktur; bu bilinen bir kısıttır. WebGL’de tarayıcı bunu üstlenir (Unity SDK).

Sunucu tarafı canlılık sondası

Sunucu, bağlantı gecikmesini ölçmek için yaklaşık 5 saniyede bir protokol düzeyi WebSocket Ping gönderir. Tarayıcı ve standart istemci kütüphaneleri Pong’u kendiliğinden yanıtlar; elle WebSocket yazıyorsanız Pong yanıtını unutmayın. Bu sonda oyuncu etkinliği sayılmaz.

Sorun giderme

Daha fazlası için sorun giderme.