实时通信

实时 API 保持连接打开，并双向发送消息。在本教程中，你会通过 WebSocket 和 Server-Sent Events 观看演示商店的订单信息流，然后通过 Socket.IO 与商店的客服台交谈，并通过 MQTT 读取仓库温度，让它们并排运行。

• 用时： 20 分钟。
• 你需要： 选择了无环境的 Alpenglow 工作区。对于 Socket.IO 和 MQTT，还需要本地服务器：在 examples/servers 中运行 bun run realtime。
• 你将学到： 连接、已存储的消息、实时日志、事件流、命名空间和确认、订阅、QoS 和保留消息。

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. 选取断开连接。日志以已由 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!"}。勾选它的确认框，让服务器被要求确认它，然后选取发送。
4. 日志显示确认 {"id": "msg_31", "delivered": true}，片刻之后是 Heidi 的回答：“Your Matterhorn 2P ships tomorrow from Bern.”
5. 要发送尚未存储的事件，请在输入框的 event 字段中输入事件名称，以 JSON 输入其参数，然后选取发送（⇧⌘↩）。

日志的每一行会标明命名空间、事件，以及确认的编号（如果有）。过滤事件可缩小日志范围。当服务器要求你确认它的某个事件时，该行会出现确认按钮。认证载荷，例如 {"token": "{{token}}"}，放在事件标签页的认证字段中。参见 Socket.IO。

4. MQTT：仓库传感器Copy Anchor Link

同样的本地服务器还在 localhost:1883 上运行一个 MQTT Broker，每 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}，标有“保留”：Broker 为之后订阅的任何人保存了它。
6. 在发布标签页中，把主题设为 warehouses/bern/door，载荷设为 {"open": true}，然后选取发布（⇧⌘↩）。订阅 warehouses/# 可看到它返回：# 匹配其下的所有级别。

连接标签页包含客户端 ID、清除会话设置、保持连接和遗嘱。Broker 的用户名和密码作为 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 中运行：会话也会在运行器中运行，并发送它们已存储的消息。