Исключение WebSocketException

Исключение WebSocketException применяется внутри обработчиков WebSocket для принудительного закрытия соединения. Оно принимает два необязательных параметра: code - числовой код закрытия и reason - текстовое пояснение причины. Когда исключение возникает, FastAPI отправляет клиенту соответствующий кадр закрытия и завершает соединение.

Если параметры не указаны, используются значения по умолчанию: код 1000 и пустая строка в качестве причины. Исключение удобно возбуждать вручную, например при неудачной аутентификации или при получении некорректных данных от клиента.

Синтаксис

from fastapi import WebSocketException

raise WebSocketException(code=1008, reason='policy violation')

Пример

Давайте создадим WebSocket-обработчик, который закрывает соединение с кодом 1008 при получении пустого сообщения:

from fastapi import FastAPI, WebSocket, WebSocketException

app = FastAPI()

@app.websocket('/ws')
async def websocket_endpoint(websocket: WebSocket):
	await websocket.accept()
	
	while True:
		data = await websocket.receive_text()
		
		if not data:
			raise WebSocketException(code=1008, reason='empty message')
		
		await websocket.send_text(f'echo: {data}')

При подключении и отправке строки 'hello' клиент получит ответ:

"echo: hello"

Если же отправить пустое сообщение, соединение закроется с кодом 1008 и причиной 'empty message'.

Пример

Давайте реализуем проверку токена и закроем соединение, если токен не совпадает с ожидаемым:

<+python+> from fastapi import FastAPI, WebSocket, WebSocketException app = FastAPI() @app.websocket('/chat') async def chat_endpoint(websocket: WebSocket): token = websocket.query_params.get('token') if token != 'abcde': raise WebSocketException(code=1008, reason='invalid token') await websocket.accept() await websocket.send_text('welcome') <-python+>

При подключении по адресу /chat?token=abcde клиент получит сообщение:

"welcome"

Если же токен окажется неверным, соединение будет закрыто с кодом 1008 и причиной 'invalid token'.

Смотрите также

атрибут code,
который задаёт код закрытия WebSocket-соединения
атрибут reason,
который хранит текстовую причину закрытия соединения
исключение WebSocketDisconnect,
которое возбуждается при разрыве соединения клиентом
исключение WebSocketRequestValidationError,
которое возникает при ошибке валидации WebSocket-запроса