`microdot.websocket` — WebSocket 지원¶

WebSocket은 HTTP를 통한 양방향 영구 연결입니다. 업그레이드 핸드셰이크 이후, 클라이언트와 서버는 동일한 소켓에서 프레임화된 메시지를 주고받습니다. SSE(단방향 푸시)와 일반 HTTP 폴링이 저렴하게 제공할 수 없는 전이중(full-duplex) 트래픽이 카메라와 브라우저 측 애플리케이션 사이에 필요할 때 사용하십시오.

class WebSocket¶

class microdot.websocket.WebSocket(request)¶

라우트가 받는 핸들입니다. with_websocket()을 사용 중일 때 핸들러에 두 번째 인수로 전달됩니다. 직접 생성하지 마십시오.

클래스 속성

max_message_length: int¶: receive()가 허용하는 최대 페이로드 크기입니다. 이보다 큰 메시지는 WebSocketError를 발생시키고 연결을 닫습니다. 0은 검사를 비활성화합니다(이 값을 설정할 경우 메모리 고갈 공격에 유의하세요). -1(기본값)은 Request.max_body_length를 사용합니다.

CONT: int¶: 연속 프레임 opcode, 0x0. 동일한 메시지에서 이전 프레임의 페이로드를 이어가는 프레임을 표시합니다. Microdot은 연속 프레임을 자체적으로 생성하지 않으며(각 메시지는 단일 프레임으로 전송됨) 수신 시에는 이를 거부하지만, 사용자 정의 프레이밍을 구현하는 애플리케이션을 위해 상수가 노출되어 있습니다.

TEXT: int¶: 텍스트 프레임 opcode, 0x1. data가 str일 때 send()가 자동으로 선택하는 opcode이며, 페이로드는 전송 시 UTF-8로 인코딩됩니다.

BINARY: int¶: 바이너리 프레임 opcode, 0x2. data가 bytes / bytearray일 때 send()가 자동으로 선택하는 opcode이며, 페이로드는 그대로 전송됩니다.

CLOSE: int¶: Close 프레임 opcode인 0x8입니다. close()에 의해 전송되며, 이를 수신하면 receive()에서 WebSocketError(“Websocket connection closed”)가 발생합니다.

PING: int¶: 핑 프레임 opcode, 0x9. Microdot은 receive() 내부에서 수신된 핑에 대해 자동으로 일치하는 PONG으로 응답합니다. 애플리케이션은 일반적으로 이를 관찰하지 않습니다.

PONG: int¶: 퐁 프레임 opcode, 0xA. PING에 대한 응답으로 자동으로 전송됩니다. 수신된 퐁은 조용히 폐기됩니다.

인스턴스 속성

request: microdot.Request¶: 원래의 microdot.Request로, 라우트 핸들러가 받은 것과 동일한 객체입니다.

closed: bool¶: close()가 실행되면 True가 됩니다. 정리 경로에서 이중 닫기를 방지하기 위해 검사하십시오.

메서드

async receive()¶: 클라이언트로부터 다음 메시지를 기다렸다가 반환합니다. 반환 타입은 프레임 opcode에 따라 결정됩니다. 텍스트 프레임은 str, 바이너리 프레임은 bytes입니다. ping 프레임에는 자동으로 pong으로 응답하고, pong 프레임은 조용히 폐기되며, close 프레임은 WebSocketError(“Websocket connection closed”)를 발생시킵니다.

async send(data, opcode: int | None = None)¶: data를 클라이언트로 전송합니다. 문자열은 텍스트 프레임으로, 바이트는 바이너리 프레임으로 전송됩니다. 이를 재정의하려면 opcode를 명시적으로 전달하십시오.

async close()¶: 닫기 프레임을 전송하고 연결을 닫힌 것으로 표시합니다. with_websocket()의 래퍼가 종료될 때 자동으로 호출됩니다.

class WebSocketError¶

exception microdot.websocket.WebSocketError¶

연결이 종료되거나 프로토콜이 위반될 때 WebSocket.receive() 내부에서 발생합니다. 정상적인 클라이언트 연결 해제를 감지하기 위해 라우트에서 사용하십시오:

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

모듈 수준 데코레이터¶

microdot.websocket.with_websocket(f)¶

라우트를 WebSocket 엔드포인트로 바꾸는 데코레이터입니다. 핸들러는 요청과 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)

핸들러의 수명은 연결 수명과 같습니다. 반환, 예외 발생 또는 클라이언트 연결 해제는 WebSocket을 깔끔하게 닫습니다.

async microdot.websocket.websocket_upgrade(request)¶

저수준 업그레이드 헬퍼입니다. 업그레이드가 조건부로 발생해야 할 때, 예를 들어 인증 검사가 통과한 후에만 발생해야 할 때 라우트 내부에서 사용하십시오:

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

업그레이드된 WebSocket을 반환합니다. 작업이 완료되면 핸들러는 microdot.Response.already_handled를 반환해야 합니다(또는 예외를 발생시켜야 합니다). Microdot이 이미 소켓을 인수했기 때문입니다.

이 구현은 표준 텍스트 및 바이너리 opcode, 핑/퐁, 깔끔한 닫기를 지원합니다. 분할(연속) 프레임은 지원되지 않습니다. 각 메시지는 단일 프레임으로 전송되며, 이는 일반적인 소규모 메시지 카메라 애플리케이션에 적합합니다.

microdot.websocket — WebSocket 지원¶

class WebSocket¶

class WebSocketError¶

모듈 수준 데코레이터¶

`microdot.websocket` — WebSocket 지원¶