Реальное время

API реального времени держат соединение открытым и обмениваются сообщениями в обе стороны. В этом руководстве вы понаблюдаете за потоком заказов демо-магазина по WebSocket и как за Server-Sent Events, затем поговорите со службой поддержки магазина по Socket.IO и прочитаете температуры складов по MQTT — всё рядом друг с другом.

• Время: 20 минут.
• Вам понадобится: рабочее пространство Alpenglow с выбранным Без окружения. Для Socket.IO и MQTT — локальные серверы: выполните bun run realtime в examples/servers.
• Вы узнаете: про подключение, сохранённые сообщения, живой журнал, потоки событий, пространства имён и подтверждения, подписки, QoS и сохранённые (retained) сообщения.

1. WebSocket: поток заказовCopy Anchor Link

1. Откройте Realtime › Order updates. Его URL — {{wsURL}}/orders, то есть wss://demo.echolot.dev/v1/orders.
2. Нажмите Соединить (⌘R). Кнопка превратится в Отключиться.
3. Вкладка Сообщения ответа заполняется: значок звена для открытого соединения, hello сервера, затем событие заказа каждые 1,5 секунды, например {"event": "order.created", "order": "ord_9Tq3Vb", …}. У отправленных сообщений стрелка вверх, у полученных — зелёная стрелка вниз. Ещё разворачивает длинное сообщение JSON.
4. На вкладке Сообщения запроса сохранённое сообщение Subscribe содержит {"op":"subscribe","channel":"orders"}. Нажмите его Отправить. Сервер отвечает {"op": "subscribed", "channel": "orders"}.
5. Введите в поле ввода внизу {"id": 42, "text": "hello"} и нажмите Отправить (⇧⌘↩). Сервер подтверждает его ответом {"op": "ack", "id": 42}. Нажмите +, чтобы сохранить сообщение на потом.
6. Сузьте журнал кнопками Все, Отправлено и Получено или введите shipped в Фильтр сообщений.
7. Нажмите Отключиться. Журнал заканчивается строкой Closed by Echolot.

Демо закрывает сеанс через три минуты (1000 Demo sessions last 3 minutes), а если вы отправите больше 20 сообщений за десять секунд, закрывает его с кодом 1008. Сохранённые сообщения с отмеченным Отправлять в прогонах отправляются по порядку после подключения, когда запрос выполняется в Прогоне или инструментом командной строки. Подробнее — в разделе WebSocket и SSE.

2. Server-Sent Events: тот же поток как стримCopy Anchor Link

1. Откройте Realtime › Order events. Это обычный HTTP-запрос GET {{baseURL}}/orders/events с заголовком Accept: text/event-stream.
2. Нажмите Отправить. Ответ откроется на вкладке События: Прослушивание… «Остановить» завершает его.
3. Событие приходит каждую секунду, каждое в своей карточке с номером и названием, например 1. order.created, а под ним id 1. После 20 событий сервер отправляет end и закрывает поток.
4. Чтобы остановиться раньше, нажмите Отменить (⌘.).

Чтобы продолжить после какого-то события, добавьте заголовок Last-Event-ID с последним увиденным id, скажем 15, и отправьте снова. Сервер пришлёт 16–20. Если ввести Last-Event-ID на вкладке Заголовки, в качестве значения предлагается {{lastEventId}}; задайте этой переменной значение или введите число.

3. Socket.IO: служба поддержкиCopy Anchor Link

Сначала запустите локальные серверы (bun run realtime). Они выведут Alpenglow realtime: Socket.IO on http://localhost:3001/support, MQTT on mqtt://localhost:1883.

1. Откройте Realtime › Support chat. Его URL — {{realtimeURL}}, http://localhost:3001. На его вкладке События Пространство имён — /support; меню метода в строке URL задаёт версию Сервер (Socket.IO 4).
2. Нажмите Соединить. Придут три события: welcome с именем агента и очередью, typing, затем message: «Grüezi! How can I help with your order?»
3. Сохранённое событие Say hello отправляет message с {"text":"Grüezi!"}. Отметьте его флажок Ack, чтобы от сервера потребовалось подтверждение, и нажмите Отправить.
4. В журнале видно подтверждение {"id": "msg_31", "delivered": true}, а чуть позже — ответ Хайди: «Your Matterhorn 2P ships tomorrow from Bern.»
5. Чтобы отправить несохранённое событие, введите его имя в поле event поля ввода, а аргументы — как JSON, и нажмите Отправить (⇧⌘↩).

В каждой строке журнала указаны пространство имён, событие и номер подтверждения, если он есть. Фильтр событий сужает журнал. Если сервер просит подтвердить одно из своих событий, в этой строке появляется кнопка Подтвердить. Данные авторизации, например {"token": "{{token}}"}, указываются в поле Авторизация на вкладке События. См. Socket.IO.

4. MQTT: датчики складовCopy Anchor Link

Те же локальные серверы запускают брокер MQTT на localhost:1883, который публикует температуры трёх складов каждые 1,5 секунды.

1. Откройте Realtime › Warehouse sensors. Его URL — mqtt://{{mqttHost}}, а Протокол в меню метода — MQTT 3.1.1.
2. На его вкладке Подписка есть подписка warehouses/+/temperature с QoS 1 и отмеченным Подписаться при подключении. + соответствует одному уровню топика.
3. Нажмите Соединить. Приходят сообщения для warehouses/zurich/temperature, warehouses/bern/temperature и warehouses/chur/temperature, например {"celsius": 6.1, "humidity": 44, …}.
4. Меню Все топики позволяет показать только один склад.
5. В поле ввода Подписка введите warehouses/status, оставьте QoS 0 и нажмите Подписка. Сразу приходит одно сообщение, {"online": 3}, с пометкой «сохранено» (retained): брокер сохранил его для всех, кто подпишется позже.
6. На вкладке Публикация задайте топик warehouses/bern/door, содержимое {"open": true} и нажмите Публикация (⇧⌘↩). Подпишитесь на warehouses/#, чтобы увидеть, как оно вернётся: # соответствует всем уровням ниже.

Вкладка Подключение содержит ID клиента, настройку чистого сеанса, Keep alive и завещание (will). Имя пользователя и пароль брокера вводятся на вкладке Авторизация как авторизация Basic; храните пароль в секретной переменной. Инструмент командной строки тоже говорит на MQTT:

echolot mqtt subscribe mqtt://localhost 'warehouses/#' --count 5

См. MQTT и echolot mqtt.

5. Рядом друг с другомCopy Anchor Link

У каждого запроса своя вкладка. Оставьте Order updates, Support chat и Warehouse sensors открытыми в трёх вкладках и подключите каждый: все соединения остаются открытыми, пока вы переключаетесь между ними. Когда сеанс закрывается, Echolot сохраняет его в Истории вместе со всем журналом сообщений, так что позже его можно перечитать (⌘Y).

Те же локальные серверы обслуживают и gRPC: выполните bun run grpc и отправьте запросы из Inventory. Watch stock передаёт потоком десяток уровней запасов и заканчивается. См. gRPC.

ДальшеCopy Anchor Link

• WebSocket и SSE: подпротоколы, бинарные сообщения, проверки сеансов.
• Socket.IO и MQTT: все настройки.
• Тестирование API и запуск в CI: сеансы выполняются и в Прогоне, отправляя свои сохранённые сообщения.