feat(lobby): implement bounded WebSocket sessions and countdown

2026-09-04 02:13:26 +03:00
parent b10c7f5972
commit 996bda9567
21 changed files with 2040 additions and 64 deletions
@@ -0,0 +1,663 @@
+#include "maze32_gateway.h"
+
+#include <inttypes.h>
+#include <stdio.h>
+#include <string.h>
+#include <sys/socket.h>
+#include <unistd.h>
+
+#include "esp_heap_caps.h"
+#include "esp_log.h"
+#include "esp_random.h"
+#include "maze32_protocol.h"
+
+static const char* TAG = "maze32_gateway";
+static const char* NAME_SUGGESTIONS[] = {
+    "Байт-Беглец", "Кот-Навигатор", "Сэр Тупичок", "Пиксельный Ёж", "Лорд Лабиринт",
+};
+
+static uint64_t now_ms(void) {
+    return (uint64_t)(esp_timer_get_time() / 1000);
+}
+
+static maze32_gateway_connection_t* find_connection(maze32_gateway_t* gateway, int socket_fd) {
+    for (size_t index = 0U; index < MAZE32_GATEWAY_CONNECTION_LIMIT; ++index) {
+        if (gateway->connections[index].active &&
+            gateway->connections[index].socket_fd == socket_fd) {
+            return &gateway->connections[index];
+        }
+    }
+    return NULL;
+}
+
+static maze32_gateway_connection_t* open_connection(maze32_gateway_t* gateway, int socket_fd) {
+    maze32_gateway_connection_t* existing = find_connection(gateway, socket_fd);
+    if (existing != NULL) {
+        return existing;
+    }
+    for (size_t index = 0U; index < MAZE32_GATEWAY_CONNECTION_LIMIT; ++index) {
+        maze32_gateway_connection_t* connection = &gateway->connections[index];
+        if (!connection->active) {
+            memset(connection, 0, sizeof(*connection));
+            connection->active = 1;
+            connection->socket_fd = socket_fd;
+            connection->rate_window_started_ms = now_ms();
+            unsigned int active_count = 0U;
+            for (size_t count_index = 0U; count_index < MAZE32_GATEWAY_CONNECTION_LIMIT;
+                 ++count_index) {
+                if (gateway->connections[count_index].active) {
+                    active_count++;
+                }
+            }
+            ESP_LOGI(TAG, "WebSocket connected: fd=%d, active=%u/%u", socket_fd, active_count,
+                     (unsigned int)MAZE32_GATEWAY_CONNECTION_LIMIT);
+            if (active_count == MAZE32_GATEWAY_CONNECTION_LIMIT) {
+                ESP_LOGI(TAG, "Six-client heap: free=%u bytes, largest=%u bytes",
+                         (unsigned int)heap_caps_get_free_size(MALLOC_CAP_8BIT),
+                         (unsigned int)heap_caps_get_largest_free_block(MALLOC_CAP_8BIT));
+            }
+            return connection;
+        }
+    }
+    return NULL;
+}
+
+static int append_text(char* output, size_t capacity, size_t* length, const char* text) {
+    size_t text_length = strlen(text);
+    if (*length + text_length >= capacity) {
+        return 0;
+    }
+    memcpy(output + *length, text, text_length);
+    *length += text_length;
+    output[*length] = '\0';
+    return 1;
+}
+
+static int append_json_string(char* output, size_t capacity, size_t* length, const char* value) {
+    if (!append_text(output, capacity, length, "\"")) {
+        return 0;
+    }
+    for (const unsigned char* cursor = (const unsigned char*)value; *cursor != '\0'; ++cursor) {
+        const char* escape = NULL;
+        if (*cursor == '"') {
+            escape = "\\\"";
+        } else if (*cursor == '\\') {
+            escape = "\\\\";
+        } else if (*cursor == '\n') {
+            escape = "\\n";
+        } else if (*cursor == '\r') {
+            escape = "\\r";
+        } else if (*cursor == '\t') {
+            escape = "\\t";
+        }
+        if (escape != NULL) {
+            if (!append_text(output, capacity, length, escape)) {
+                return 0;
+            }
+        } else {
+            char byte[2] = {(char)*cursor, '\0'};
+            if (!append_text(output, capacity, length, byte)) {
+                return 0;
+            }
+        }
+    }
+    return append_text(output, capacity, length, "\"");
+}
+
+static uint32_t next_server_sequence(maze32_gateway_t* gateway) {
+    gateway->server_sequence++;
+    if (gateway->server_sequence == 0U) {
+        gateway->server_sequence = 1U;
+    }
+    return gateway->server_sequence;
+}
+
+static int enqueue(maze32_gateway_t* gateway, int socket_fd, const char* payload) {
+    size_t length = strlen(payload);
+    if (gateway->outgoing_count >= MAZE32_GATEWAY_QUEUE_LIMIT ||
+        length >= MAZE32_GATEWAY_OUTGOING_LIMIT) {
+        ESP_LOGW(TAG, "Bounded outgoing queue rejected a message for fd=%d", socket_fd);
+        return 0;
+    }
+    size_t index = (gateway->outgoing_head + gateway->outgoing_count) % MAZE32_GATEWAY_QUEUE_LIMIT;
+    maze32_gateway_outgoing_t* entry = &gateway->outgoing[index];
+    entry->socket_fd = socket_fd;
+    entry->length = length;
+    memcpy(entry->payload, payload, length + 1U);
+    gateway->outgoing_count++;
+    return 1;
+}
+
+static void drain_queue(maze32_gateway_t* gateway) {
+    while (gateway->outgoing_count > 0U) {
+        maze32_gateway_outgoing_t* entry = &gateway->outgoing[gateway->outgoing_head];
+        httpd_ws_frame_t frame = {
+            .final = true,
+            .fragmented = false,
+            .type = HTTPD_WS_TYPE_TEXT,
+            .payload = (uint8_t*)entry->payload,
+            .len = entry->length,
+        };
+        esp_err_t result = httpd_ws_send_frame_async(gateway->server, entry->socket_fd, &frame);
+        if (result != ESP_OK) {
+            ESP_LOGW(TAG, "WebSocket send failed for fd=%d: %s", entry->socket_fd,
+                     esp_err_to_name(result));
+        }
+        gateway->outgoing_head = (gateway->outgoing_head + 1U) % MAZE32_GATEWAY_QUEUE_LIMIT;
+        gateway->outgoing_count--;
+    }
+}
+
+static void send_error(maze32_gateway_t* gateway, int socket_fd, const char* request_id,
+                       const char* code, const char* message) {
+    char response[MAZE32_GATEWAY_OUTGOING_LIMIT] = "";
+    size_t length = 0U;
+    char prefix[128];
+    int written = snprintf(prefix, sizeof(prefix), "{\"v\":1,\"type\":\"error\",\"seq\":%" PRIu32,
+                           next_server_sequence(gateway));
+    if (written < 0 || (size_t)written >= sizeof(prefix) ||
+        !append_text(response, sizeof(response), &length, prefix)) {
+        return;
+    }
+    if (request_id != NULL && request_id[0] != '\0') {
+        if (!append_text(response, sizeof(response), &length, ",\"requestId\":") ||
+            !append_json_string(response, sizeof(response), &length, request_id)) {
+            return;
+        }
+    }
+    if (!append_text(response, sizeof(response), &length, ",\"payload\":{\"code\":") ||
+        !append_json_string(response, sizeof(response), &length, code) ||
+        !append_text(response, sizeof(response), &length, ",\"message\":") ||
+        !append_json_string(response, sizeof(response), &length, message) ||
+        !append_text(response, sizeof(response), &length, "}}")) {
+        return;
+    }
+    enqueue(gateway, socket_fd, response);
+}
+
+static const maze32_session_t* player_for_slot(const maze32_lobby_t* lobby, unsigned int slot) {
+    for (size_t index = 0U; index < MAZE32_SESSION_LIMIT; ++index) {
+        const maze32_session_t* session = &lobby->sessions[index];
+        if (session->role == MAZE32_ROLE_PLAYER && session->player_slot == slot) {
+            return session;
+        }
+    }
+    return NULL;
+}
+
+static int build_snapshot(maze32_gateway_t* gateway, char* response, size_t capacity) {
+    uint32_t sequence = next_server_sequence(gateway);
+    int written =
+        snprintf(response, capacity,
+                 "{\"v\":1,\"type\":\"lobby\",\"seq\":%" PRIu32
+                 ",\"payload\":{\"revision\":%" PRIu32 ",\"phase\":\"%s\","
+                 "\"ready\":%s,\"ownerSlot\":1,\"players\":[",
+                 sequence, gateway->lobby.revision, maze32_lobby_phase_name(gateway->lobby.phase),
+                 maze32_lobby_ready(&gateway->lobby) ? "true" : "false");
+    if (written < 0 || (size_t)written >= capacity) {
+        return 0;
+    }
+    size_t length = (size_t)written;
+    for (unsigned int slot = 1U; slot <= MAZE32_PLAYER_LIMIT; ++slot) {
+        const maze32_session_t* player = player_for_slot(&gateway->lobby, slot);
+        char prefix[96];
+        written = snprintf(prefix, sizeof(prefix),
+                           "%s{\"slot\":%u,\"name\":", slot == 1U ? "" : ",", slot);
+        if (written < 0 || (size_t)written >= sizeof(prefix) ||
+            !append_text(response, capacity, &length, prefix) ||
+            !append_json_string(response, capacity, &length, player == NULL ? "" : player->name)) {
+            return 0;
+        }
+        written = snprintf(prefix, sizeof(prefix), ",\"occupied\":%s,\"connected\":%s}",
+                           player == NULL ? "false" : "true",
+                           player != NULL && player->connected ? "true" : "false");
+        if (written < 0 || (size_t)written >= sizeof(prefix) ||
+            !append_text(response, capacity, &length, prefix)) {
+            return 0;
+        }
+    }
+    char suffix[128];
+    written = snprintf(suffix, sizeof(suffix), "],\"observers\":%u,\"observerLimit\":%u}}",
+                       maze32_lobby_connected_observers(&gateway->lobby),
+                       (unsigned int)MAZE32_OBSERVER_LIMIT);
+    return written >= 0 && (size_t)written < sizeof(suffix) &&
+           append_text(response, capacity, &length, suffix);
+}
+
+static void broadcast_snapshot(maze32_gateway_t* gateway) {
+    char response[MAZE32_GATEWAY_OUTGOING_LIMIT];
+    if (!build_snapshot(gateway, response, sizeof(response))) {
+        ESP_LOGE(TAG, "Lobby snapshot exceeded its fixed buffer");
+        return;
+    }
+    for (size_t index = 0U; index < MAZE32_GATEWAY_CONNECTION_LIMIT; ++index) {
+        maze32_gateway_connection_t* connection = &gateway->connections[index];
+        if (connection->active &&
+            maze32_lobby_session_for_connection(&gateway->lobby, connection->socket_fd) != NULL) {
+            enqueue(gateway, connection->socket_fd, response);
+        }
+    }
+}
+
+static void send_session(maze32_gateway_t* gateway, int socket_fd, const maze32_session_t* session,
+                         const char* request_id) {
+    char response[MAZE32_GATEWAY_OUTGOING_LIMIT] = "";
+    size_t length = 0U;
+    char prefix[160];
+    int written = snprintf(prefix, sizeof(prefix), "{\"v\":1,\"type\":\"session\",\"seq\":%" PRIu32,
+                           next_server_sequence(gateway));
+    if (written < 0 || (size_t)written >= sizeof(prefix) ||
+        !append_text(response, sizeof(response), &length, prefix)) {
+        return;
+    }
+    if (request_id[0] != '\0' &&
+        (!append_text(response, sizeof(response), &length, ",\"requestId\":") ||
+         !append_json_string(response, sizeof(response), &length, request_id))) {
+        return;
+    }
+    written =
+        snprintf(prefix, sizeof(prefix), ",\"payload\":{\"role\":\"%s\",\"slot\":%u,\"token\":",
+                 session->role == MAZE32_ROLE_PLAYER ? "player" : "observer", session->player_slot);
+    if (written < 0 || (size_t)written >= sizeof(prefix) ||
+        !append_text(response, sizeof(response), &length, prefix) ||
+        !append_json_string(response, sizeof(response), &length, session->token) ||
+        !append_text(response, sizeof(response), &length, "}}")) {
+        return;
+    }
+    enqueue(gateway, socket_fd, response);
+}
+
+static void generate_token(maze32_gateway_t* gateway, char* token) {
+    static const char HEX[] = "0123456789abcdef";
+    uint8_t bytes[MAZE32_SESSION_TOKEN_BYTES];
+    for (;;) {
+        esp_fill_random(bytes, sizeof(bytes));
+        for (size_t index = 0U; index < sizeof(bytes); ++index) {
+            token[index * 2U] = HEX[bytes[index] >> 4U];
+            token[index * 2U + 1U] = HEX[bytes[index] & 0x0fU];
+        }
+        token[MAZE32_SESSION_TOKEN_HEX_LENGTH] = '\0';
+        int collision = 0;
+        for (size_t index = 0U; index < MAZE32_SESSION_LIMIT; ++index) {
+            if (gateway->lobby.sessions[index].role != MAZE32_ROLE_NONE &&
+                strcmp(gateway->lobby.sessions[index].token, token) == 0) {
+                collision = 1;
+                break;
+            }
+        }
+        if (!collision) {
+            return;
+        }
+    }
+}
+
+static void send_lobby_error(maze32_gateway_t* gateway, int socket_fd, const char* request_id,
+                             maze32_lobby_result_t result) {
+    switch (result) {
+        case MAZE32_LOBBY_INVALID_NAME:
+            send_error(gateway, socket_fd, request_id, "invalid_name",
+                       "Имя должно быть длиной от 1 до 32 байт без пробелов по краям");
+            break;
+        case MAZE32_LOBBY_DUPLICATE_NAME:
+            send_error(gateway, socket_fd, request_id, "duplicate_name", "Это имя уже занято");
+            break;
+        case MAZE32_LOBBY_ROLE_FULL:
+            send_error(gateway, socket_fd, request_id, "role_full", "Свободных мест больше нет");
+            break;
+        case MAZE32_LOBBY_INVALID_TOKEN:
+            send_error(gateway, socket_fd, request_id, "invalid_token", "Сессия не найдена");
+            break;
+        case MAZE32_LOBBY_SESSION_CONNECTED:
+            send_error(gateway, socket_fd, request_id, "session_connected",
+                       "Эта сессия уже подключена");
+            break;
+        case MAZE32_LOBBY_NOT_OWNER:
+            send_error(gateway, socket_fd, request_id, "not_owner",
+                       "Запустить игру может только Игрок 1");
+            break;
+        case MAZE32_LOBBY_NOT_READY:
+            send_error(gateway, socket_fd, request_id, "not_ready",
+                       "Для старта нужны оба игрока онлайн");
+            break;
+        case MAZE32_LOBBY_INVALID_PHASE:
+            send_error(gateway, socket_fd, request_id, "invalid_phase",
+                       "Лобби уже запустило обратный отсчёт");
+            break;
+        default:
+            send_error(gateway, socket_fd, request_id, "request_rejected", "Команда отклонена");
+            break;
+    }
+}
+
+static void send_suggestion(maze32_gateway_t* gateway, int socket_fd, const char* request_id) {
+    const char* suggestion = NULL;
+    size_t suggestion_count = sizeof(NAME_SUGGESTIONS) / sizeof(NAME_SUGGESTIONS[0]);
+    for (size_t attempt = 0U; attempt < suggestion_count; ++attempt) {
+        size_t index = gateway->suggestion_index++ % suggestion_count;
+        int occupied = 0;
+        for (size_t session_index = 0U; session_index < MAZE32_SESSION_LIMIT; ++session_index) {
+            const maze32_session_t* session = &gateway->lobby.sessions[session_index];
+            if (session->role == MAZE32_ROLE_PLAYER &&
+                strcmp(session->name, NAME_SUGGESTIONS[index]) == 0) {
+                occupied = 1;
+                break;
+            }
+        }
+        if (!occupied) {
+            suggestion = NAME_SUGGESTIONS[index];
+            break;
+        }
+    }
+    if (suggestion == NULL) {
+        send_error(gateway, socket_fd, request_id, "no_suggestion",
+                   "Все смешные имена уже разобрали");
+        return;
+    }
+    char response[MAZE32_GATEWAY_OUTGOING_LIMIT] = "";
+    size_t length = 0U;
+    char prefix[128];
+    int written =
+        snprintf(prefix, sizeof(prefix), "{\"v\":1,\"type\":\"name_suggestion\",\"seq\":%" PRIu32,
+                 next_server_sequence(gateway));
+    if (written < 0 || (size_t)written >= sizeof(prefix) ||
+        !append_text(response, sizeof(response), &length, prefix)) {
+        return;
+    }
+    if (request_id[0] != '\0' &&
+        (!append_text(response, sizeof(response), &length, ",\"requestId\":") ||
+         !append_json_string(response, sizeof(response), &length, request_id))) {
+        return;
+    }
+    if (append_text(response, sizeof(response), &length, ",\"payload\":{\"name\":") &&
+        append_json_string(response, sizeof(response), &length, suggestion) &&
+        append_text(response, sizeof(response), &length, "}}")) {
+        enqueue(gateway, socket_fd, response);
+    }
+}
+
+static void broadcast_countdown(maze32_gateway_t* gateway) {
+    char response[MAZE32_GATEWAY_OUTGOING_LIMIT];
+    int written = snprintf(response, sizeof(response),
+                           "{\"v\":1,\"type\":\"countdown\",\"seq\":%" PRIu32
+                           ",\"payload\":{\"steps\":[3,2,1],\"startedAtMs\":%" PRIu64
+                           ",\"activationAtMs\":%" PRIu64 "}}",
+                           next_server_sequence(gateway), gateway->lobby.countdown_started_ms,
+                           gateway->lobby.activation_ms);
+    if (written < 0 || (size_t)written >= sizeof(response)) {
+        return;
+    }
+    for (size_t index = 0U; index < MAZE32_SESSION_LIMIT; ++index) {
+        const maze32_session_t* session = &gateway->lobby.sessions[index];
+        if (session->role == MAZE32_ROLE_PLAYER && session->connected) {
+            enqueue(gateway, session->connection_id, response);
+        }
+    }
+}
+
+static void countdown_finished_work(void* context) {
+    maze32_gateway_t* gateway = context;
+    if (!maze32_lobby_activate_if_due(&gateway->lobby, now_ms())) {
+        return;
+    }
+    char response[MAZE32_GATEWAY_OUTGOING_LIMIT];
+    int written = snprintf(response, sizeof(response),
+                           "{\"v\":1,\"type\":\"active\",\"seq\":%" PRIu32
+                           ",\"payload\":{\"activatedAtMs\":%" PRIu64 "}}",
+                           next_server_sequence(gateway), gateway->lobby.activation_ms);
+    if (written >= 0 && (size_t)written < sizeof(response)) {
+        for (size_t index = 0U; index < MAZE32_SESSION_LIMIT; ++index) {
+            const maze32_session_t* session = &gateway->lobby.sessions[index];
+            if (session->role != MAZE32_ROLE_NONE && session->connected) {
+                enqueue(gateway, session->connection_id, response);
+            }
+        }
+    }
+    broadcast_snapshot(gateway);
+    drain_queue(gateway);
+    ESP_LOGI(TAG, "Lobby became active at server time %" PRIu64 " ms",
+             gateway->lobby.activation_ms);
+}
+
+static void countdown_timer_callback(void* context) {
+    maze32_gateway_t* gateway = context;
+    if (gateway->server != NULL) {
+        esp_err_t result = httpd_queue_work(gateway->server, countdown_finished_work, gateway);
+        if (result != ESP_OK) {
+            ESP_LOGE(TAG, "Could not queue countdown activation: %s", esp_err_to_name(result));
+        }
+    }
+}
+
+static int rate_limit_allows(maze32_gateway_connection_t* connection, uint64_t current_ms) {
+    if (current_ms - connection->rate_window_started_ms >= 1000U) {
+        connection->rate_window_started_ms = current_ms;
+        connection->messages_in_window = 0U;
+    }
+    connection->messages_in_window++;
+    return connection->messages_in_window <= MAZE32_GATEWAY_RATE_LIMIT_PER_SECOND;
+}
+
+static void handle_message(maze32_gateway_t* gateway, maze32_gateway_connection_t* connection,
+                           const maze32_client_message_t* message) {
+    int socket_fd = connection->socket_fd;
+    if (message->type == MAZE32_MESSAGE_SUGGEST_NAME) {
+        send_suggestion(gateway, socket_fd, message->request_id);
+        return;
+    }
+    if (message->type == MAZE32_MESSAGE_JOIN) {
+        if (maze32_lobby_session_for_connection(&gateway->lobby, socket_fd) != NULL) {
+            send_error(gateway, socket_fd, message->request_id, "already_joined",
+                       "Сессия уже выбрала роль");
+            return;
+        }
+        char token[MAZE32_SESSION_TOKEN_HEX_LENGTH + 1U];
+        generate_token(gateway, token);
+        maze32_session_t* session = NULL;
+        maze32_lobby_result_t result =
+            message->role == MAZE32_ROLE_PLAYER
+                ? maze32_lobby_join_player(&gateway->lobby, socket_fd, message->name, token,
+                                           &session)
+                : maze32_lobby_join_observer(&gateway->lobby, socket_fd, token, &session);
+        if (result != MAZE32_LOBBY_OK) {
+            send_lobby_error(gateway, socket_fd, message->request_id, result);
+            return;
+        }
+        send_session(gateway, socket_fd, session, message->request_id);
+        broadcast_snapshot(gateway);
+        return;
+    }
+    if (message->type == MAZE32_MESSAGE_RESTORE) {
+        if (maze32_lobby_session_for_connection(&gateway->lobby, socket_fd) != NULL) {
+            send_error(gateway, socket_fd, message->request_id, "already_joined",
+                       "Сессия уже восстановлена");
+            return;
+        }
+        maze32_session_t* session = NULL;
+        maze32_lobby_result_t result =
+            maze32_lobby_restore(&gateway->lobby, socket_fd, message->token, &session);
+        if (result != MAZE32_LOBBY_OK) {
+            send_lobby_error(gateway, socket_fd, message->request_id, result);
+            return;
+        }
+        send_session(gateway, socket_fd, session, message->request_id);
+        broadcast_snapshot(gateway);
+        return;
+    }
+
+    const maze32_session_t* session =
+        maze32_lobby_session_for_connection(&gateway->lobby, socket_fd);
+    if (session == NULL) {
+        send_error(gateway, socket_fd, message->request_id, "unauthorized",
+                   "Сначала выберите роль или восстановите сессию");
+        return;
+    }
+    if (message->type == MAZE32_MESSAGE_START) {
+        maze32_lobby_result_t result = maze32_lobby_start(&gateway->lobby, socket_fd, now_ms());
+        if (result != MAZE32_LOBBY_OK) {
+            send_lobby_error(gateway, socket_fd, message->request_id, result);
+            return;
+        }
+        broadcast_snapshot(gateway);
+        broadcast_countdown(gateway);
+        esp_err_t timer_result =
+            esp_timer_start_once(gateway->countdown_timer, MAZE32_COUNTDOWN_DURATION_MS * 1000U);
+        if (timer_result != ESP_OK) {
+            ESP_LOGE(TAG, "Countdown timer could not start: %s", esp_err_to_name(timer_result));
+        }
+        return;
+    }
+    if (message->type == MAZE32_MESSAGE_HEARTBEAT) {
+        char response[MAZE32_GATEWAY_OUTGOING_LIMIT] = "";
+        size_t length = 0U;
+        char prefix[128];
+        int written = snprintf(prefix, sizeof(prefix), "{\"v\":1,\"type\":\"ack\",\"seq\":%" PRIu32,
+                               next_server_sequence(gateway));
+        if (written >= 0 && (size_t)written < sizeof(prefix) &&
+            append_text(response, sizeof(response), &length, prefix) &&
+            append_text(response, sizeof(response), &length, ",\"requestId\":") &&
+            append_json_string(response, sizeof(response), &length, message->request_id) &&
+            append_text(response, sizeof(response), &length,
+                        ",\"payload\":{\"command\":\"heartbeat\"}}")) {
+            enqueue(gateway, socket_fd, response);
+        }
+    }
+}
+
+static esp_err_t websocket_handler(httpd_req_t* request) {
+    maze32_gateway_t* gateway = request->user_ctx;
+    int socket_fd = httpd_req_to_sockfd(request);
+    maze32_gateway_connection_t* connection = find_connection(gateway, socket_fd);
+    if (connection == NULL) {
+        connection = open_connection(gateway, socket_fd);
+        if (connection == NULL) {
+            ESP_LOGW(TAG, "WebSocket connection limit reached; rejecting fd=%d", socket_fd);
+            shutdown(socket_fd, SHUT_RDWR);
+            return ESP_OK;
+        }
+    }
+    httpd_ws_frame_t frame = {0};
+    esp_err_t result = httpd_ws_recv_frame(request, &frame, 0U);
+    if (result != ESP_OK) {
+        return result;
+    }
+    if (frame.len > MAZE32_PROTOCOL_MESSAGE_LIMIT) {
+        ESP_LOGW(TAG, "Oversized WebSocket frame rejected: fd=%d, length=%u", socket_fd,
+                 (unsigned int)frame.len);
+        shutdown(socket_fd, SHUT_RDWR);
+        return ESP_OK;
+    }
+    uint8_t payload[MAZE32_PROTOCOL_MESSAGE_LIMIT + 1U];
+    frame.payload = payload;
+    result = httpd_ws_recv_frame(request, &frame, MAZE32_PROTOCOL_MESSAGE_LIMIT);
+    if (result != ESP_OK) {
+        return result;
+    }
+    if (frame.type == HTTPD_WS_TYPE_CLOSE) {
+        return ESP_OK;
+    }
+    if (frame.type != HTTPD_WS_TYPE_TEXT) {
+        send_error(gateway, socket_fd, "", "text_required", "Нужен текстовый JSON-пакет");
+        drain_queue(gateway);
+        return ESP_OK;
+    }
+    payload[frame.len] = '\0';
+    if (!rate_limit_allows(connection, now_ms())) {
+        send_error(gateway, socket_fd, "", "rate_limited", "Слишком много команд");
+        drain_queue(gateway);
+        return ESP_OK;
+    }
+
+    maze32_client_message_t message;
+    maze32_protocol_result_t parse_result =
+        maze32_protocol_parse((const char*)payload, frame.len, &message);
+    if (parse_result != MAZE32_PROTOCOL_OK) {
+        send_error(gateway, socket_fd, "", maze32_protocol_result_name(parse_result),
+                   "Пакет не прошёл проверку протокола");
+        drain_queue(gateway);
+        return ESP_OK;
+    }
+    if (message.sequence <= connection->last_client_sequence) {
+        send_error(gateway, socket_fd, message.request_id, "stale_sequence",
+                   "Команда устарела или уже обработана");
+        drain_queue(gateway);
+        return ESP_OK;
+    }
+    connection->last_client_sequence = message.sequence;
+    handle_message(gateway, connection, &message);
+    drain_queue(gateway);
+    return ESP_OK;
+}
+
+static esp_err_t websocket_pre_handshake(httpd_req_t* request) {
+    maze32_gateway_t* gateway = request->user_ctx;
+    int socket_fd = httpd_req_to_sockfd(request);
+    if (open_connection(gateway, socket_fd) == NULL) {
+        ESP_LOGW(TAG, "WebSocket connection limit reached; rejecting fd=%d", socket_fd);
+        return ESP_ERR_NO_MEM;
+    }
+    return ESP_OK;
+}
+
+esp_err_t maze32_gateway_init(maze32_gateway_t* gateway) {
+    if (gateway == NULL) {
+        return ESP_ERR_INVALID_ARG;
+    }
+    memset(gateway, 0, sizeof(*gateway));
+    maze32_lobby_init(&gateway->lobby);
+    const esp_timer_create_args_t timer_arguments = {
+        .callback = countdown_timer_callback,
+        .arg = gateway,
+        .dispatch_method = ESP_TIMER_TASK,
+        .name = "lobby_countdown",
+        .skip_unhandled_events = true,
+    };
+    return esp_timer_create(&timer_arguments, &gateway->countdown_timer);
+}
+
+void maze32_gateway_set_server(maze32_gateway_t* gateway, httpd_handle_t server) {
+    if (gateway != NULL) {
+        gateway->server = server;
+    }
+}
+
+esp_err_t maze32_gateway_register(httpd_handle_t server, maze32_gateway_t* gateway) {
+    if (server == NULL || gateway == NULL) {
+        return ESP_ERR_INVALID_ARG;
+    }
+    maze32_gateway_set_server(gateway, server);
+    const httpd_uri_t websocket = {
+        .uri = "/ws",
+        .method = HTTP_GET,
+        .handler = websocket_handler,
+        .user_ctx = gateway,
+        .is_websocket = true,
+        .ws_pre_handshake_cb = websocket_pre_handshake,
+    };
+    esp_err_t result = httpd_register_uri_handler(server, &websocket);
+    if (result == ESP_OK) {
+        ESP_LOGI(TAG, "WebSocket gateway ready: connections=%u, message=%u, queue=%u",
+                 (unsigned int)MAZE32_GATEWAY_CONNECTION_LIMIT,
+                 (unsigned int)MAZE32_PROTOCOL_MESSAGE_LIMIT,
+                 (unsigned int)MAZE32_GATEWAY_QUEUE_LIMIT);
+    }
+    return result;
+}
+
+void maze32_gateway_close_socket(httpd_handle_t server, int socket_fd) {
+    maze32_gateway_t* gateway = httpd_get_global_user_ctx(server);
+    if (gateway != NULL) {
+        maze32_gateway_connection_t* connection = find_connection(gateway, socket_fd);
+        if (connection != NULL) {
+            maze32_lobby_disconnect(&gateway->lobby, socket_fd);
+            memset(connection, 0, sizeof(*connection));
+            broadcast_snapshot(gateway);
+            drain_queue(gateway);
+            ESP_LOGI(TAG, "WebSocket disconnected: fd=%d", socket_fd);
+        }
+    }
+    close(socket_fd);
+}
+
+int maze32_gateway_can_reconfigure(const maze32_gateway_t* gateway) {
+    return gateway != NULL && maze32_lobby_can_reconfigure(&gateway->lobby);
+}