Обычный GraphQL POST может работать, пока subscriptions полностью сломаны: длительное двунаправленное соединение использует другой транспорт и часто другой route. Первый контрольный признак — WebSocket handshake. Успешное переключение по HTTP/1.1 отвечает 101 Switching Protocols.
Сравните прямое подключение к backend в тестовой сети и публичный wss URL через proxy. Если прямое работает, правьте маршрут, headers или timeout proxy; если оба не работают, проверяйте сервер и согласованный subprotocol.
Status handshake сужает поиск
| Результат | Чаще всего означает | Что проверить |
|---|---|---|
| 101, затем мгновенный close | Subprotocol/auth/init не принят | Sec-WebSocket-Protocol, close code, connection_ack |
| 200 HTML/JSON | Запрос попал в обычный HTTP GraphQL route | location и path rewrite |
| 301/302 | Redirect во время handshake | Сразу использовать конечный wss URL |
| 400/426 | Нет/неверен Upgrade | Upgrade и Connection headers |
| 404 | Proxy изменил путь | Слеши в location/proxy_pass |
| 502/504 | Backend недоступен или timeout | Upstream address, logs, read timeout |
В браузере откройте DevTools → Network → WS, а не только Fetch/XHR. Нужны request URL, status, request/response headers, frames и close code. Authorization payload и персональные данные из connection_init перед публикацией лога удаляют.
NGINX передаёт hop-by-hop headers явно
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
location /graphql-ws {
proxy_pass http://graphql_backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header Host $host;
proxy_read_timeout 75s;
}
}NGINX указывает, что Upgrade и Connection — hop-by-hop headers и не проходят к upstream автоматически. Для актуальной версии сверяйте необходимость явного proxy_http_version 1.1: документация NGINX помечает различие версий. Значение timeout в примере условное и должно быть больше интервала heartbeat с запасом.
Path проверяем без догадок о слешах
location /graphql-ws и proxy_pass с URI либо без него меняют upstream path по разным правилам. Запишите фактический path в access log proxy и route, который видит GraphQL server. Redirect с /graphql-ws на /graphql-ws/ лучше убрать из handshake и сразу настроить клиент на конечный URL.
- Публичный клиент использует wss на HTTPS-сайте, а не смешанный ws.
- DNS и TLS certificate соответствуют публичному host.
- Origin проверяется по явному allowlist на backend.
- Sticky sessions включаются только если состояние соединения действительно локально узлу.
- Load balancer timeout согласован с ping/pong или protocol heartbeat.
Subprotocol должен совпасть на клиенте и сервере
Популярный протокол graphql-ws использует значение graphql-transport-ws в Sec-WebSocket-Protocol и описывает сообщения connection_init, connection_ack и subscribe. Он не совместим с устаревшим subscriptions-transport-ws. Proxy должен сохранить header выбора subprotocol, а обе стороны — говорить на одной версии протокола.
GraphQL Specification описывает семантику Subscription, но конкретный сетевой транспорт выбирает реализация. Поэтому наличие type Subscription в schema ещё не подтверждает правильную настройку WebSocket endpoint.
Обрыв через фиксированное время выдаёт timeout
NGINX по умолчанию закрывает proxied WebSocket, если upstream долго ничего не передаёт; официальная документация приводит интервал 60 секунд и предлагает изменить proxy_read_timeout либо отправлять ping frames. Не делайте timeout бесконечным: heartbeat обнаруживает мёртвые соединения и позволяет освободить ресурсы.
- Подключиться и дождаться connection_ack.
- Оставить подписку без событий дольше текущего idle timeout.
- Увидеть ping/pong или protocol keepalive в согласованном интервале.
- Остановить backend и получить ожидаемый close/reconnect.
- Перезапустить один upstream и проверить восстановление subscription.
- Убедиться, что reconnect не создаёт дубликаты активной подписки.
Приёмка проверяет данные после восстановления
Недостаточно получить 101. После connection_ack подпишитесь на тестовое событие, получите один payload, разорвите соединение и подтвердите reconnect по политике клиента. Если события имеют sequence ID, проверьте пропуск и дубль; WebSocket transport сам по себе не гарантирует replay бизнес-событий после disconnect.
Для разбора достаточно короткого сетевого следа
Приложите обезличенные handshake headers, status, close code/reason, публичный path, фрагмент NGINX location, версии client/server transport и временную шкалу disconnect. Токены из connection_init и полные subscription variables удалите. По этим данным обычно видно, где соединение перестало быть WebSocket.