docs/protocol.md

协议规范

本文档定义了 InterConnect-Server 使用的 REST 和 WebSocket 协议格式。所有负载均为 JSON 格式。

认证 (Authentication)

• REST: 在请求头中发送 Authorization: Bearer <API_KEY>。
• WebSocket: 连接到 ws://<host>/ws?api_key=<API_KEY>（HTTPS 下使用 wss）。

事件对象 (Event Object)

事件通过 REST 发送到服务器，并广播给 WebSocket 客户端。 服务器仅验证必填字段和 event_type 值。 data 负载会原样传递。

必填字段：

• event_type (字符串)
• server_name (字符串)
• timestamp (字符串, ISO 8601)
• data (对象)

有效的 event_type 值：

• player_join
• player_leave
• message
• server_command

事件示例：

{
  "event_type": "player_join",
  "server_name": "survival-01",
  "timestamp": "2024-01-21T12:34:56.789Z",
  "data": {
    "player": "Steve"
  }
}

REST 端点 (REST Endpoints)

POST /api/events

提交一个事件以进行存储和广播。

请求：

• 认证：任意有效密钥
• Content-Type: application/json
• Body: 事件对象

响应：

{
  "message": "Event received and broadcasted"
}

错误：

• 400 如果缺少必填字段或 event_type 无效
• 401 如果 API 密钥丢失/无效

POST /api/server/command

发送服务器命令。这也将广播一个 server_command 事件。

请求：

• 认证：Regular 或 Admin 密钥
• Content-Type: application/json
• Body:

{
  "command": "say Hello from API",
  "server_id": "survival-01"
}

注意：

• 当 Admin 密钥未绑定到服务器时，必须提供 server_id。
• 服务器对 Admin 命令强制执行允许/阻止列表。

响应：

{
  "message": "Command sent successfully",
  "command": "say Hello from API",
  "server_id": "survival-01"
}

WebSocket 消息 (WebSocket Messages)

客户端到服务器

Ping:

{ "type": "ping" }

Pong 响应:

{ "type": "pong" }

服务器到客户端

广播事件：

{
  "type": "minecraft_event",
  "event": {
    "event_type": "message",
    "server_name": "survival-01",
    "timestamp": "2024-01-21T12:34:56.789Z",
    "data": {
      "player": "Alex",
      "message": "Hello world"
    }
  },
  "source_key_id_prefix": "a1b2c3d4"
}

source_key_id_prefix 是提交事件或命令的 API 密钥 ID 的前 8 个字符。它不是 API 密钥本身。