microdot.websocket --- Dukungan WebSocket

WebSocket adalah koneksi persisten dua arah melalui HTTP -- setelah jabat tangan peningkatan, klien dan server mengirim dan menerima pesan berbingkai pada soket yang sama. Gunakan WebSocket saat kamera dan aplikasi sisi browser membutuhkan lalu lintas full-duplex yang tidak dapat diberikan secara efisien oleh SSE (push satu arah) dan polling HTTP biasa.

class WebSocket

class microdot.websocket.WebSocket(request)

Handle yang diterima oleh rute. Diteruskan ke handler sebagai argumen kedua ketika with_websocket() digunakan; jangan dibuat langsung.

Atribut kelas

max_message_length: int

Ukuran payload maksimum yang akan diterima oleh receive(). Pesan yang lebih besar dari ini akan memunculkan WebSocketError dan menutup koneksi. 0 menonaktifkan pemeriksaan ini (waspadai serangan habis memori jika Anda mengaturnya). -1 (default) menggunakan Request.max_body_length.

CONT: int

Opcode bingkai lanjutan, 0x0. Menandai bingkai yang melanjutkan payload bingkai sebelumnya untuk pesan yang sama. Microdot tidak menghasilkan bingkai lanjutan sendiri (setiap pesan dikirim sebagai satu bingkai) dan menolaknya saat menerima, tetapi konstanta ini diekspos untuk aplikasi yang mengimplementasikan pembingkaian khusus.

TEXT: int

Opcode bingkai teks, 0x1. Opcode yang dipilih secara otomatis oleh send() ketika data adalah str; payload di-encode dengan UTF-8 saat keluar.

BINARY: int

Opcode bingkai biner, 0x2. Opcode yang dipilih secara otomatis oleh send() ketika data adalah bytes / bytearray; payload dikirim apa adanya.

CLOSE: int

Opcode bingkai penutup, 0x8. Dikirim oleh close(); menerimanya akan memunculkan WebSocketError ("Websocket connection closed") dari receive().

PING: int

Opcode bingkai ping, 0x9. Microdot menjawab ping yang masuk dengan PONG yang sesuai secara otomatis di dalam receive(); aplikasi biasanya tidak mengamatinya.

PONG: int

Opcode bingkai pong, 0xA. Dikirim secara otomatis sebagai balasan terhadap PING. Pong yang masuk diabaikan.

Atribut instance

request: microdot.Request

microdot.Request yang berasal -- objek yang sama yang diterima oleh handler rute.

closed: bool

True setelah close() dijalankan. Periksa untuk menghindari penutupan ganda pada jalur pembersihan.

Metode

async receive()

Tunggu dan kembalikan pesan berikutnya dari klien. Tipe kembalian sesuai dengan opcode bingkai: str untuk bingkai teks, bytes untuk bingkai biner. Bingkai ping dijawab otomatis dengan pong; bingkai pong diabaikan; bingkai close memunculkan WebSocketError ("Websocket connection closed").

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

Kirim data ke klien. String dikirim sebagai bingkai teks, bytes sebagai bingkai biner; berikan opcode secara eksplisit untuk mengesampingkan ini.

async close()

Kirim bingkai penutup dan tandai koneksi sebagai ditutup. Dipanggil secara otomatis ketika pembungkus with_websocket() selesai.

class WebSocketError

exception microdot.websocket.WebSocketError

Dimunculkan di dalam WebSocket.receive() ketika koneksi berakhir atau protokol dilanggar. Gunakan ini dalam sebuah rute untuk mendeteksi pemutusan klien yang normal:

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

Dekorator tingkat modul

microdot.websocket.with_websocket(f)

Dekorator yang mengubah rute menjadi endpoint WebSocket. Handler menerima request dan objek WebSocket

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)

Masa hidup handler sama dengan masa hidup koneksi. Mengembalikan nilai, memunculkan pengecualian, atau pemutusan klien akan menutup WebSocket secara bersih.

async microdot.websocket.websocket_upgrade(request)

Helper peningkatan tingkat rendah. Gunakan ini di dalam rute ketika peningkatan harus dilakukan secara kondisional -- misalnya hanya setelah pemeriksaan otorisasi berhasil:

@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())

Mengembalikan WebSocket yang telah ditingkatkan. Handler harus mengembalikan microdot.Response.already_handled (atau memunculkan pengecualian) setelah selesai -- microdot telah mengambil alih soket.

Implementasi mendukung opcode teks dan biner standar, ping / pong, dan penutupan yang bersih. Bingkai terfragmentasi (lanjutan) tidak didukung -- setiap pesan dikirim sebagai satu bingkai, yang sesuai untuk aplikasi kamera dengan pesan-pesan kecil yang tipikal.