Limitler ve yaygın hatalar · WebSocket

Kaynak sürümünü, varsayılanları, destek sınırlarını ve mevcut belgelerle kaynak kod arasındaki farkları karşılaştırın.

Bu rehber crates.io'da yayımlanan lilyrs 0.1.0 facade'inin websocket feature'ını ve lily_websocket 0.1.0 bileşenini esas alır. Kaynak dayanağı 78ca08b822aa192623c7bcffd90edaf06e4f8e55 commit'idir. Rust alt sınırı ve doğrulanan toolchain 1.96.1, edition 2024'tür. Canonical kurulum registry kullanır; framework checkout'u gerekmez. Belge ile implementation farklıysa bu rehber implementation'ı izler.

Varsayılanlar ve sabit sınırlar#

Aşağıdaki değerler kapasite tavsiyesi değildir. Adet, byte ve süre limitleri farklı kaynakları yönetir; kendi mesaj boyutu ve eşzamanlılığınıza göre ayarlayın.

Ayar / kural	Varsayılan / sınır
Merkezi websocket enabled / adres	false / `127.0.0.1:8081`
Endpoint	`/ws`, tek exact canonical path; en çok 256 byte
Bağlantı kapasitesi	1000
Inbound reassembled mesaj	1 MiB
Tek inbound frame	256 KiB
Tek outbound encoded application mesajı	1 MiB; WebSocket/backplane overhead hariç
Inbound waiting queue	16 mesaj, 1 MiB toplam
Outbound queue	256 mesaj, 1 MiB toplam admission byte'ı
Outbound admission / write timeout	Ayrı ayrı 5000 ms; kabul aralığı 100..=300000 ms
Write buffer threshold / ceiling	128 KiB / 2 MiB
Buffer validation	Ceiling threshold'dan büyük; outbound mesaj + server-frame header sığmalı
Message / cleanup / connection middleware / lifecycle timeout	30 / 10 / 10 / 30 s; her biri 1..=300 s
Handshake timeout	10 s, pozitif
Ping / Pong / application idle	30 / 10 / 60 s, pozitif
Supported subprotocol / require	`["lily.v2"]` / false
Origin allow-list / any / missing	Boş / false / false
Trusted proxy list / XFF hop cap	Boş / 16; hop aralığı 1..=64
Bağlantı başına oda sayısı / isim	128 / en çok 128 ASCII route-token byte
Explicit broadcast ID / exclusions / room-list	Her listede en çok 256 giriş
Namespace / birleşik event route	128 / 256 ASCII byte
`message_id`, `ack_id`	En çok 128 byte bounded identifier
Envelope metadata	En çok 32 alan; key 128 byte, value 1024 byte
Handshake / connection / message local tipleri	Her map için en çok 32 distinct tip
Ham handshake header sayısı / name	64 / 128 byte
Ham header value / merge edilmiş repeatable value	8 KiB / 16 KiB
Typed action argümanı / payload consumer	16 / en çok 1
Effective middleware plan	64 giriş, aynı concrete TypeId tekrarı yasak
Effective guard plan	TypeId tekrarı yasak; bu sürümde ayrıca 64 guard sınırı uygulanmıyor
Principal ID	256 UTF-8 byte; non-empty, no surrounding whitespace/control
Application error code / public message / close reason	64 / 1024 / 123 byte

Byte sınırları toplam process RSS garantisi değildir. TLS buffer'ı, kullanıcı callback belleği ve retained nesneler ayrıca kaynak kullanır. İlgili kurulumlar configuration, backpressure ve transport sayfalarındadır.

Yaygın hatalar#

Belirti / varsayım	Kontrol edilecek nokta
Default builder build etmiyor	Merkezi websocket `enabled = true`
Browser bağlanamıyor	Exact Origin, `/ws`, namespace, subprotocol
CLI bağlanamıyor	Missing Origin için açık izin ve `lily.v2` teklifi
ACK yerine hata geliyor	İstemci event'inde `ack_id` var mı?
Payload parse olmuyor	Raw frame yerine canonical envelope ve doğru content-kind
Guard iki kez kayıtlı	Global/controller/action effective planında duplicate tip
Disconnected çalışmıyor	Connected gerçekten çağrılıp `Ok(())` döndü mü?
Scoped servis bağlantı boyunca saklandı	Scope dışına Arc taşımayın; owned local veya doğru lifetime kullanın
Pg cancellation imzası uyuşmuyor	WS ve ortak Pg cancellation farklı tiplerdir
Broadcast success teslim sanılıyor	Sonuç queue/publish acceptance'tır
AsyncAPI endpoint bulunamıyor	Mevcut destek metadata kaydıyla sınırlıdır
Direct client eklenince build config istiyor	`websocket-client` single kaydını açar; manuel profil için `websocket-client-di` seçin
Factory derlemesi feature çakışması veriyor	Base feature yerine `*-factory` seçin; bağımlılık grafiğinde single/factory birleşmesin
Worker cancellation tipi uyuşmuyor	`BackgroundCancellation` kullanın; mesaj cancellation tipi farklıdır

Belge–kaynak farkları#

C01 — Stage bazlı timeout anlatımı#

Crate controller rehberi forward middleware, guard, action ve reverse çıkışlar için ayrı normal süreler tarif eder. Güncel kaynak bütün normal pipeline'ı tek absolute message deadline ile yürütür. Bu sitede action → controller → app önceliği ve tek bütçe kullanılır; handshake/cleanup cap'leri ayrıdır.

C02 — Cooperative sahiplik hazır#

Crate rustdoc girişindeki gelecek faz anlatımının aksine cooperative pencere ve retained execution owner desteği uygulanmıştır. Kesilen normal işin scope/task sahipliği korunur. Rehber bunu mevcut yetenek olarak anlatır; blocking poll ve bütçe sınırları yine geçerlidir.

C03 — Cancellation ve send cutoff#

Shutdown migration metni execution cancellation'ın send yetkisini doğrudan kaldırdığı izlenimini verir. Güncel outbound yolu cooperative execution cutoff'u bekler. Shutdown sayfasında sinyal, bounded continuation ve yetkinin bitişi ayrı anlatılır.

C04 — Guard callback parametresi#

Çözüldü. 14 Eylül incelemesinde eksik olan cancellation parametresi yayımlanan sürümün README guard özetinde artık vardır. Geçerli imza can_activate(&self, &mut WsMessageExchange, ExecutionCancellation) şeklindedir. Guard örneği aynı imzayı kullanır; bu kayıt açık bir çelişki olarak değerlendirilmemelidir.

C05 — BaseGateway facade istisnası#

Derive crate'inin rustdoc metni umbrella facade henüz yokmuş gibi konuşur. lilyrs artık yayımlanmıştır; ancak BaseGateway hâlâ facade'dan re-export edilmez ve makro kodu doğrudan crate yolları üretir. Gateway rehberindeki açık bağımlılık istisnası bu nedenle korunur. Genel facade keşfi anlatımı bu derive'a uygulanmaz.

Ayrı kapsam sınırları#

Pg cancellation tip farkı ve AsyncAPI generator yokluğu belge çelişkisi olarak sayılmaz; mevcut entegrasyon sınırlarıdır. is_fully_delivered() adı peer delivery garantisi oluşturmaz. Disconnected'ın başarılı connected gerektirmesi de mevcut davranıştır.

Socket.IO/SignalR wire uyumluluğu, otomatik CRUD/join server action'ları, bağlantı içinde namespace değiştirme, kalıcı offline inbox/replay veya exactly-once teslim desteği varsaymayın. HTTP file upload/SSE ve hazır JWT/OIDC provider bu server'ın hazır API'si değildir. Uygulama ömründeki işler için add_background_service mevcuttur; worker rehberi ayrı cancellation ve scope sözleşmesini anlatır.

Wire qualification sınırı#

Frame/message limitleri, fragmentation ve kontrol frame'leri için kaynak testleri bulunur. Ancak Tungstenite bir Text frame'in declared payload'ı tamamlanmadan UTF-8 kontrolünü tamamlamayabilir. Geçersiz text action'a dispatch edilmez ve uygun terminal durumda 1007 seçilir; daha erken TCP read anında fail-fast garantisi verilmez.

Bu durum TECHNICAL_DEBT.md içinde LWS-TD-001 olarak kayıtlıdır. Bütün Autobahn vakalarının bu rehber çalışmasında geçtiği iddia edilmez. Test sayfası derleme, socket ve çevreye bağlı doğrulamaları ayrı listeler.