microdot.websocket — WebSocket desteği

WebSocket’ler HTTP üzerinden çift yönlü kalıcı bir bağlantıdır – bir yükseltme el sıkışmasından sonra istemci ve sunucu aynı soket üzerinde çerçevelenmiş mesajlar gönderip alır. Bunları, kamera ile bir tarayıcı tarafı uygulamanın, SSE’nin (tek yönlü gönderim) ve düz HTTP yoklamasının ucuza sağlayamadığı tam çift yönlü trafiğe ihtiyaç duyduğu durumlarda kullanın.

class WebSocket

class microdot.websocket.WebSocket(request)

Yönlendirmenin (route) aldığı tanıtıcı (handle). with_websocket() kullanımdayken işleyicilere ikinci argüman olarak iletilir; doğrudan oluşturmayın.

Sınıf öznitelikleri

max_message_length: int

receive() metodunun kabul edeceği en büyük yük (payload) boyutu. Bundan daha büyük mesajlar WebSocketError hatası fırlatır ve bağlantıyı kapatır. 0 denetimi devre dışı bırakır (bunu ayarlarsanız bellek tükenmesi saldırılarına dikkat edin). -1 (varsayılan) Request.max_body_length değerini kullanır.

CONT: int

Devam çerçevesi (continuation-frame) işlem kodu, 0x0. Aynı mesaj için bir önceki çerçevenin yükünü sürdüren bir çerçeveyi işaretler. Microdot devam çerçevelerini kendisi üretmez (her mesaj tek bir çerçeve olarak gönderilir) ve alındığında bunları reddeder, ancak sabit, özel çerçeveleme uygulayan uygulamalar için açığa çıkarılmıştır.

TEXT: int

Metin çerçevesi (text-frame) işlem kodu, 0x1. data bir str olduğunda send() metodunun otomatik olarak seçtiği işlem kodu; yük çıkışta UTF-8 ile kodlanır.

BINARY: int

İkili çerçeve (binary-frame) işlem kodu, 0x2. data bir bytes / bytearray olduğunda send() metodunun otomatik olarak seçtiği işlem kodu; yük olduğu gibi gönderilir.

CLOSE: int

Kapatma çerçevesi (close-frame) işlem kodu, 0x8. close() tarafından gönderilir; bir tanesinin alınması receive() içinden bir WebSocketError (“Websocket connection closed”) fırlatır.

PING: int

Ping çerçevesi (ping-frame) işlem kodu, 0x9. Microdot gelen ping’lere receive() içinde otomatik olarak eşleşen bir PONG ile yanıt verir; uygulama bunları normalde gözlemlemez.

PONG: int

Pong çerçevesi (pong-frame) işlem kodu, 0xA. Bir PING yanıtında otomatik olarak gönderilir. Gelen pong’lar sessizce atılır.

Örnek (instance) öznitelikleri

request: microdot.Request

Kaynağı oluşturan microdot.Request – yönlendirme işleyicisinin aldığı nesnenin aynısı.

closed: bool

close() çalıştırıldıktan sonra True. Temizleme yollarında çift kapatmayı önlemek için kontrol edin.

Metotlar

async receive()

İstemciden gelen bir sonraki mesajı bekle ve döndür. Dönüş tipi çerçeve işlem koduyla eşleşir: metin çerçeveleri için str, ikili çerçeveler için bytes. ping çerçeveleri otomatik olarak bir pong ile yanıtlanır; pong çerçeveleri sessizce atılır; bir close çerçevesi bir WebSocketError (“Websocket connection closed”) fırlatır.

async send(data, opcode: int | None = None)

İstemciye data gönder. Dizeler metin çerçeveleri olarak, baytlar ikili çerçeveler olarak gönderilir; geçersiz kılmak için opcode değerini açıkça verin.

async close()

Bir kapatma çerçevesi gönder ve bağlantıyı kapalı olarak işaretle. with_websocket() sarmalayıcısı çıktığında otomatik olarak çağrılır.

class WebSocketError

exception microdot.websocket.WebSocketError

Bağlantı sonlandığında veya protokol ihlal edildiğinde WebSocket.receive() içinde fırlatılır. Normal istemci kopmalarını tespit etmek için bunu bir yönlendirmede kullanın:

try:
    message = await ws.receive()
except WebSocketError:
    # client closed the connection

Modül düzeyindeki dekoratörler

microdot.websocket.with_websocket(f)

Bir yönlendirmeyi bir WebSocket uç noktasına dönüştüren dekoratör. İşleyici, isteği ve bir WebSocket nesnesini alır:

from microdot import Microdot
from microdot.websocket import with_websocket

app = Microdot()

@app.get('/echo')
@with_websocket
async def echo(request, ws):
    while True:
        msg = await ws.receive()
        await ws.send(msg)

İşleyicinin ömrü bağlantının ömrüne eşittir. Geri dönmek, hata fırlatmak veya bir istemci kopması WebSocket’i düzgün bir şekilde kapatır.

async microdot.websocket.websocket_upgrade(request)

Düşük seviyeli yükseltme yardımcısı. Yükseltmenin koşullu olarak gerçekleşmesi gerektiğinde bunu bir yönlendirmenin içinde kullanın – örneğin yalnızca bir yetkilendirme kontrolü başarılı olduktan sonra:

@app.get('/private')
async def private(request):
    if not authenticate(request):
        abort(401)
    ws = await websocket_upgrade(request)
    while True:
        msg = await ws.receive()
        await ws.send(msg.upper())

Yükseltilmiş WebSocket nesnesini döndürür. İşleyici, işi bittiğinde microdot.Response.already_handled döndürmelidir (veya hata fırlatmalıdır) – microdot soketi zaten devralmıştır.

Uygulama, standart metin ve ikili işlem kodlarını, ping / pong’u ve düzgün bir kapatmayı destekler. Parçalanmış (devam) çerçeveler desteklenmez – her mesaj tek bir çerçeve olarak gönderilir; bu da tipik küçük mesajlı kamera uygulamaları için uygundur.