Skip to content

Latest commit

 

History

History
198 lines (109 loc) · 5.53 KB

internal-protocol.md

File metadata and controls

198 lines (109 loc) · 5.53 KB

内部通信协议

综述

协议目的

  1. 协调评测机和控制端的双向通信。

  2. 验证评测机的身份，防止恶意攻击

  3. 兼容缓存机制的运行

名称解释

评测机端的 SecretKey

评测机端的 SecretKey，简称 SK。由控制端生成，与 AccessKey 相关联。由管理员填入评测机的配置文件中。如不慎泄密或失密，应使用控制端的管理功能注销对应的密钥对。

评测机端的 AccessKey

评测机端的 SecretKey，简称 AK。用于识别不同的评测机及其密钥，无保密必要

会话令牌

在评测机开启 ws 连接前，向控制端申请的一次性会话令牌。对单个 ws 连接有效。

任务令牌

流量控制系统的组成部分。令牌与评测机关联。向评测机下发任务需占用一个对应评测机的任务令牌并登记到活动任务令牌队列中。当评测结束并返回后，释放任务令牌至可用池中。

组成部分

协议包含两个主要部分，一个 WebSocket 连接用于评测机状态上报、评测系统状态管理、评测任务的发放和状态更新，以及一套 HTTP API 用于权限认证和管理。

大体流程

  1. 建立连接

    1. 评测端使用 SecretKey 和 AccessKey 向控制端申请会话 token。

    2. 使用 token 建立 ws 连接

  2. 评测

    1. 通过 ws 连接接受任务，发送心跳等

    2. 通过 ws 连接更新评测任务状态和结果

  3. 软关机

    1. 控制端通过 ws 发出软关机指令并停止发放新任务

    2. 评测端继续通过 ws 发送心跳，更新已有评测任务状态和结果

    3. 评测端发送最终心跳，关闭连接并给出关闭理由

    4. 控制端记录关机状态，等评测端全部关闭或超时后关闭

WebSocket 消息格式

WebSocket 连接地址为 /v1/judgers/websocket

参数名 值类型 必选？ 说明
token string true 已获取的会话令牌

消息

所有消息具有四个字段：

参数名 值类型 必选？ 说明
type "req"/"res" true 消息种类
seq number true 消息序列号
time string true 发送时间
body unknown true 消息载荷

type 是消息种类，只有两种取值 "req" 和 "res"。

seq 是该消息的序列号，定义为无符号 32 位整数，控制端和评测端分别计数，采取自然溢出策略。如果该消息是响应，那么它的序列号必须与发送方请求消息的序列号相同。

time 是该消息的发送时间，定义为 RFC3339 格式的字符串。

body 是消息的具体内容，必须为 plain object。

在控制端与评测端的 ws 连接中传输的消息必须符合该定义，以 JSON 格式序列化为文本。

请求消息

请求消息的 body 具有两个字段：

参数名 值类型 必选？ 说明
method string true RPC 方法名
args unknown true RPC 参数

args 必须为 plain object 或 null

响应消息

响应消息的 body 具有一个字段：

参数名 值类型 必选？ 说明
output unknown true RPC 参数

output 必须为 plain object 或 null

或者

参数名 值类型 必选？ 说明
error ErrorInfo true RPC 错误信息

RPC 定义

Judge

提供方：评测端

控制端向评测端发送评测任务。

Exit

提供方：控制端，评测端

控制端要求评测端下线，或评测端主动向控制端报告即将下线。

控制端应当停止分发任务，清理资源。

收到对方响应后可以主动断开连接。

控制端可以要求评测端等待一段时间后重新连接。

Log

提供方：控制端

评测端向控制端发送日志。

Control

提供方：评测端

控制端获取或改变评测端的连接设置，评测端应当返回改变后的连接设置。

ReportStatus

提供方：控制端

评测端向控制端发送状态报告。

如果一段时间后控制端没有收到状态报告，即可判定评测端故障离线。

控制端应当停止分发任务，清理资源，断开连接。

UpdateJudges

提供方：控制端

评测端向控制端批量发送评测任务的最新状态。

FinishJudges

提供方：控制端

评测端向控制端批量发送评测任务的最终结果。

HTTP 消息格式

  1. 任意请求均需签名，具体请见公共定义。

  2. 不同版本的协议使用不同前缀，现在使用 /v1

  3. POST 限制请求体大小为 1MB

评测机登录

URL： /v1/judgers/token

方法： POST

请求体：AcquireTokenRequest

参数名 值类型 必选？ 说明
maxTaskCount decInt true 声明评测端评测能力的整数
coreCount decInt false 系统逻辑核心数
name string false 评测机的名字，不建议重复
systemInfo string false 评测机的系统环境、软件及版本，可以重复

成功状态下返回

AcquireTokenOutput

失败则返回

ErrorInfo