WebSocket

Экран WebSocket — это клиент WebSocket: он открывает одно соединение с сервисом — с заголовками и подпротоколами, которых ждёт сервис, — отправляет текст или байты и перечисляет все сообщения, приходящие и уходящие, новые внизу. С его помощью можно опробовать живой API, пульт управления или устройство, говорящее по WebSocket, прежде чем описывать работу с ним в эксперименте.

Подключение

1. Откройте WebSocket.
2. В поле URL введите адрес: ws://127.0.0.1:9001/ или wss://example.com/socket.
3. Если сервис этого требует, заполните поле Подпротоколы и добавьте заголовки в блоке Заголовки (заголовок Authorization с токеном, cookie).
4. Нажмите Подключить. Пока выполняется переход на WebSocket, на кнопке написано Подключение…; когда он завершён, поля блокируются, а кнопка превращается в Отключить.

Поле	Что это	По умолчанию
URL	ws:// или wss://, хост, необязательный порт (80 для ws, 443 для wss) и путь	ws://127.0.0.1:9001/
Подпротоколы	Подпротоколы, которые предлагаются, через запятую, по убыванию предпочтения; сервер выбирает один. В имени нет пробелов, запятых и слешей.	нет
Заголовки	Дополнительные заголовки запроса перехода; + заголовок добавляет строку. Строка без имени отбрасывается.	нет

На подключение — разрешение имени, TCP-соединение, TLS для wss:// и переход — отводится 10 секунд. URL сохраняется при переключении экранов и при перезапуске приложения; заголовки и подпротоколы — нет.

Когда соединение установлено, панель показывает:

Элемент	Что это
Состояние	открыто или, когда соединение закончилось: закрыто вами или сервером, с кодом закрытия, либо разорвано, если связь оборвалась без закрытия
Причина	Причина, названная закрывающей стороной, если она есть
Подпротокол	Подпротокол, выбранный сервером, или —
Сервер	IP:port сервера
Переход	Сколько заняли подключение и переход, в миллисекундах

Соединение — это задача: оно появляется в полосе задач, и остановить его можно и оттуда.

Защищённые соединения

wss:// доверяет тем же сертификатам, что и HTTPS в этой системе: сервер, чьему сертификату система не доверяет (самоподписанный, просроченный, другое имя), отклоняется с сообщением «Не удалось установить защищённое соединение с …». Настройки, позволяющей пропустить проверку, нет.

Отправка сообщения

1. В блоке Сообщение выберите Текст или Двоичное (hex).
2. Напишите сообщение. Для двоичного запишите байты парами шестнадцатеричных цифр: de ad be ef.
3. Нажмите Отправить или Ctrl+Enter в поле сообщения.

Сообщение не должно превышать 16 МиБ (16 777 216 байт; для двоичного считаются байты, а не шестнадцатеричные цифры) — тот же предел действует для приходящего сообщения и для узла Отправка WebSocket. Более длинное отклоняется с сообщением Too long: at most 16777216 ещё до отправки, а соединение остаётся открытым.

Если текстовое сообщение — JSON, кнопка Форматировать JSON оформляет его отступами перед отправкой. Сообщение сохраняется при переключении экранов и при перезапуске приложения.

Чтение сообщений

Список Сообщения показывает принятое (↓) и отправленное (↑), новые внизу, с временем, началом сообщения (300 символов) и размером; двоичное сообщение показывает свои байты в hex и помечено плашкой двоичное. Над списком — сколько сообщений принято и отправлено. Список следует за новыми сообщениями, пока он прокручен до конца; прокрутите вверх — и он останется там, где вы.

Щёлкните сообщение, чтобы увидеть его целиком под списком: JSON с отступами, двоичное — в hex. Кнопка Изменить как сообщение копирует его в поле сообщения, чтобы отправить снова или изменить. Очень длинное сообщение показано частично — текст до 64 КиБ, двоичное до 4096 байт — и тогда его нельзя скопировать, потому что оно ушло бы обрезанным.

Экран хранит последние 2000 сообщений; кнопка Очистить очищает список. Если сервис шлёт быстрее, чем экран успевает принять, — больше 2000 за десятую долю секунды, — самые старые из них в список не попадают и учитываются как «не показано». В Инспекторе они остаются, пока захват включён.

Закрытие

Кнопка Отключить отправляет кадр закрытия с кодом 1000 (нормальное закрытие) и до 2 секунд ждёт ответа сервера, прежде чем разорвать соединение. Тогда состояние читается как «закрыто с кодом 1000». Когда закрывает сервер, состояние показывает его код и причину; когда соединение рвётся без кадра закрытия, оно читается как разорвано, а консоль объясняет почему.

На пинги сервера Signal Lab отвечает сам; пинги и понги в списке не показываются. Соединение заканчивается и тогда, когда приходит сообщение больше 16 МиБ, и когда отправка сообщения занимает больше 10 секунд, потому что сервер перестал читать. (Отправка сообщения больше 16 МиБ вами самим отклоняется и ничего не завершает.)

В Инспекторе

Когда захват включён, трафик соединения появляется с протоколом ws и источником websocket:

Сводка	Что это
CONNECT ws://… (subprotocol)	Соединение открыто
TEXT …	Текстовое сообщение и его начало
BINARY n B …	Двоичное сообщение, его размер и первые 16 байт
CLOSE code reason	Кадр закрытия, отправленный или полученный

Каждый кадр сообщения хранит свои байты. Пока трафик небольшой, захватывается каждое сообщение; загруженное соединение ограничено 200 кадрами в секунду, а следующий захваченный кадр сообщает, сколько пропущено (+n not shown). См. Инспектор.

В экспериментах

Диалог по WebSocket описывают четыре узла. Соединение открывается одним узлом, а остальные ссылаются на него:

Узел	Что он делает
Подключение WebSocket	Открывает соединение до конца запуска. Его URL и заголовки принимают {{templates}}, так что в них можно подставить токен, извлечённый ранее. Подробнее
Отправка WebSocket	Отправляет текстовое или двоичное сообщение по соединению. Подробнее
Ожидание WebSocket	Ждёт сообщение, содержимое которого подходит, как это делает Ждать UDP; JSON-сообщения затем можно читать по полям. Подробнее
Закрытие WebSocket	Закрывает соединение с рукопожатием закрытия: код 1000 или 3000–4999 для собственных кодов приложения и причина до 123 байт. Подробнее

Соединение, которое к концу запуска (или к его остановке) ещё открыто, закрывается корректно. Шаблон Эхо WebSocket — готовый пример.

Из командной строки

signallab send ws делает один обмен: подключается, отправляет сообщение, ждёт ответа, если вы его запросили, и закрывает соединение.

signallab send ws ws://127.0.0.1:9001/ --text '{"type":"ping"}' --expect pong

Рукопожатие и то, что было отправлено, уходят в стандартный поток ошибок, ответ — в стандартный вывод:

Connected to ws://127.0.0.1:9001/ in 4 ms
Sent 15 bytes
{"type":"pong"}

--hex отправляет двоичное сообщение; -H добавляет заголовок, а --protocol предлагает подпротокол (оба можно повторять). --expect TEXT, --expect-regex RE или --wait (любое сообщение) задают, какого ответа ждать, в течение --timeout миллисекунд (по умолчанию 2000). Код завершения 1, если ответ не пришёл или соединение не удалось. См. Командная строка.

Проблемы

Что вы видите	Обычная причина
… is not a WebSocket address	URL не начинается с ws:// или wss://, или в нём нет хоста.
… answered HTTP n instead of switching to WebSocket	Сервер отказал в переходе: неверный путь (404), отсутствующий или неверный токен (401, 403). Начало его ответа — в технических подробностях.
… did not take any of the subprotocols offered	Вы предложили подпротоколы, а сервер не выбрал ни одного из них или ответил подпротоколом, которого вы не предлагали.
… is not a subprotocol name	Имя с пробелом, запятой или слешем.
The header … cannot be sent with the upgrade	В имени или значении заголовка есть символы, недопустимые в HTTP.
… refused the connection	На этом порту никто не слушает.
A secure connection to … could not be made	Сертификату здесь не доверяют, или не удалось установить TLS. См. Защищённые соединения.
The connection with … broke: the server did not keep to the WebSocket protocol	Сервер прислал то, что не является корректным WebSocket.
A WebSocket message is limited to … bytes	Сервер прислал сообщение больше 16 МиБ, из-за чего соединение закрывается.
Too long: at most 16777216	Сообщение, которое вы пытались отправить, больше 16 МиБ. Ничего не отправлено; соединение открыто.

Все сообщения об ошибках перечислены в разделе Сообщения об ошибках.