5.6.2.2 Reach的RPC协议规范

5.6.2.2 Reach的RPC协议规范

Reach的RPC协议（后续，将使用“协议”或“它”指代）是一款基于JSON实例的RPC协议。

它将使用HTTPS协议进行传输 （如基于TLS的HTTP协议）。

请求中必须要包含 X-API-Key 头部，其值为服务器与RPC客户端之间共享的秘密信息。我们称其为API密钥。通常这个值来自环境变量REACH_RPC_KEY，是24个随机字节的Base64编码信息。

需要使用 POST 这一HTTP方法发送请求。

请求指定通过HTTP请求目标调用的RPC方法)。

HTTP请求体内必须要包含一个使用JSON编码的数组。请求应将 Content-Type 标头设置为 application/json; charset=utf-8来表明这一点。这个数组将会被解释为RPC方法)的参数。

响应体中需要包含一个使用JSON编码的值。响应应当设置Content-Type标头为：application/json; charset=utf-8。

响应会包含RPC句柄，其字符串内容指明了存储在服务端无法被序列化为JSON的中间数据资源。

RPC方法)既可以是同步值RPC方法)也可以是交互式RPC方法)。

—

同步值RPC方法消耗参数并产生一个唯一的结果，不需要与客户端进行进一步互动。该结果通过响应体发送。

例如，formatCurrency是一个同步值RPC方法)。形如formatCurrency("19283.1035819471", 4)的调用将会用如下HTTP会话进行表示，其中符号+对应的是HTTP请求数据，-则对应的是HTTP响应数据：

—

交互式RPC方法 使用参数，包括交互式RPC callback)的说明，并产生一个交互式RPC continuation) 。

交互式 RPC callback是一个JSON对象的键，其值会绑定为’true’，表示交互式RPC方法)的发起者在这个调用执行期间响应进一步的数据请求。

交互式 RPC continuation 是一个符合如下要求的JSON对象：

• {t: "Done", ans}，其中ans是原始交互式RPC方法)的最终值。
• {t: "Kont", kid, m, args}，其中 kid 是RPC句柄)，m是交互式RPC callback)方法的字符串名，而 args 是对应方法所需要的参数数组。

当 Kont 值产生时，交互式RPC方法)将会暂停直到/kont这一RPC方法)被执行，并获得RPC句柄)和交互式RPC回调)的返回值。/kont的RPC方法)结果是另一个交互式的RPC continuation)。

客户端可以在交互式RPC方法)暂停时执行任何RPC方法(tech._interactive._rpc._method)。

服务器可以多次重复使用同一个交互式RPC continuation)进行处理。

例如，可以参考一个后端)执行交互式RPC方法)过程。交互的例子可以用下面的HTTP会话表示，请求行用+表示，响应行用-表示。