全局聊天
全局聊天 是一个典型的 Web 2 即时通讯子系统。它被设计用于给用户提供与游戏内容本身无关的聊天平台,i.e. 参与聊天的身份是用户,而非用户扮演的角色。
一条全局聊天消息通过以下消息编码:
| 字段 | 标识符 | 描述 | 格式 |
|---|---|---|---|
| 发件人 | sender | 发件人用户名;如果字段缺失,则为服务器通告 | 不含空格的非空 ASCII 字符串 |
| 发件时间 | time | 发件的 UNIX 时间戳 | 64 位无符号整数 |
| 内容 | content | 聊天消息内容 | UTF-8 字符串 |
| HTML 开关 | html | 内容 是否应当被解释为 HTML, 否则为纯文本 | 布尔值 |
客户端应当在界面中向登录后的用户提供发送聊天功能。
全局聊天 API 被设计为 RESTful 的。为了发送一条新的消息,客户端只需要向 https://server.vitium.dev/api/chat POST 以 JSON 编码的聊天数据。
如果请求是合法的,在正常情况下,服务端应当保存客户端发送的消息并返回 HTTP 200.
这个操作需要 验证身份 。令牌所授权的用户应当与聊天消息的发件人字段一致。
客户端应当在界面中保存一定时间或数量之内的聊天记录,并即时更新并显示最新聊天。
全局聊天消息的接收同样通过 RESTful API 实现。服务端应当提供两个 API: 同步的和异步的。
接收聊天不需要验证身份,i.e. 未登录用户亦可读取全局聊天。
同步接收用来取得服务端上所有指定时刻之后的聊天消息。客户端可以利用这一机制在用户刚登录时获取一次聊天记录。
通过 GET https://server.vitium.dev/api/chat , 并设置 URL 查询参数 after 为所需要的毫秒 UNIX 时间戳,服务端应当返回以 JSON 列表编码的 after 后的所有聊天消息。
异步接收用于获取服务端收到的实时聊天消息。这通过 服务器发送事件 实现。客户端应当始终跟踪这一 API 以保证用户看到的聊天被即时更新。
GET https://server.vitium.dev/api/chat 将返回服务器发送事件。每当有新的聊天消息,服务器将更新一个事件,其 data 字段为 JSON 编码的聊天数据。