9/TSP

9/TSP

Titanic 服务协议

Titanic 服务协议 (TSP) 定义了一套服务、请求和回复，实现了 Titanic 模式，用于在任意连接的客户端和工作节点网络中进行断开连接的持久消息传递。

许可证

版权所有 (c) 2011 iMatix Corporation。

本规范是自由软件；您可以根据自由软件基金会发布的 GNU 通用公共许可证的条款重新分发和/或修改它；可以是许可证的第 3 版，也可以是（由您选择）任何更高版本。

分发本规范是希望它会有用，但没有任何担保；甚至不包括适销性或特定用途适用性的默示担保。有关更多详情，请参阅 GNU 通用公共许可证。

您应该已经随本程序收到了 GNU 通用公共许可证的副本；如果未收到，请参阅 https://gnu.ac.cn/licenses。

变更流程

本规范是一个自由开放的标准（参见“自由开放标准的定义"）并受数字标准组织的共识导向规范系统 (COSS) 管辖（参见“共识导向规范系统"）。

语言

本文档中的关键词“必须”、“不得”、“必需”、“应”、“不应”、“应该”、“不应该”、“推荐”、“可以”和“可选”应按 RFC 2119 中的描述进行解释（参见“RFC 中表示要求等级的关键词"）。

目标

Titanic 服务协议 (TSP) 定义了一套服务、请求和回复，实现了 Titanic 模式，用于在任意连接的客户端和工作节点网络中进行断开连接的持久消息传递。

Titanic 模式在指南的第 4 章中进行了阐述（参见“ØMQ - 指南"），作为一种简单的基于磁盘的可靠消息传递设计。Titanic 允许客户端和工作节点不必同时连接到网络即可工作，并定义了用于安全存储请求和检索回复的握手机制。

TSP 旨在正式规范客户端应用程序与 Titanic 模式任意实现之间的接口。

架构

概述

Titanic 是建立在 Majordomo 协议 ([/spec:7/MDP 7/MDP]) 之上的一个层。TSP 客户端使用 MDP/客户端与 MDP 经纪人通信。Titanic 对工作节点无需进行修改，工作节点使用 MDP/工作节点协议与 MDP 经纪人通信。

Titanic 模式将持久性放在经纪人之外，作为一个代理服务，对客户端来说像一个工作节点，对工作节点来说像一个客户端。

Figure

服务

一个 Titanic 实现（即“服务器”）必须实现这些服务

  • titanic.request - 客户端通过此服务要求服务器存储新的请求。
  • titanic.reply - 客户端通过此服务查询服务器是否有可用的回复。
  • titanic.close - 客户端通过此服务告知服务器已完成处理回复。

titanic.request 服务

titanic.request 服务接受一个请求，将其持久存储，并返回该请求的 UUID（通用唯一标识符）。它是一个包含 2 个或更多帧的多部分请求消息，如下所示

  • 帧 0: 服务名称（可打印字符串）
  • 帧 1+: 请求体（不透明二进制）

请注意，此请求消息是通过 MDP 传输的。服务名称是目标服务，例如“echo”。titanic.request 服务必须回复 1 个或更多帧，如下所示

  • 帧 0: 状态码（下文解释）
  • 帧 1: 请求的 UUID，如果成功

状态码必须是下文“状态帧”部分列出的代码之一。UUID 必须格式化为 32 个十六进制字符（'0' 到 '9' 以及 'A' 到 'Z' 或 'a' 到 'z'）。

titanic.reply 服务

titanic.reply 服务接受一个 UUID，如果该 UUID 存在回复，则返回回复消息。它接受一个包含 1 个帧的请求消息，如下所示

  • 帧 0: UUID（由 titanic.request 返回）

titanic.reply 服务必须回复 1 个或更多帧，如下所示

  • 帧 0: 状态码（下文解释）
  • 帧 1+: 请求体（不透明二进制），如果成功

状态码必须是下文“状态帧”部分列出的代码之一。UUID 必须格式化为 32 个可打印的十六进制字符（'0' 到 '9' 以及 'A' 到 'Z' 或 'a' 到 'z'）。

titanic.reply 服务是幂等的，成功发送给客户端后不得删除回复。对同一个 UUID 发送多次 titanic.reply 请求，应返回相同的响应给客户端，直到且除非请求被执行。参见下文“请求执行”部分。

titanic.close 服务

titanic.close 服务接受一个 UUID 并删除该 UUID 的任何请求和回复。它接受一个包含 1 个帧的请求消息，如下所示

  • 帧 0: UUID（由 titanic.request 返回）

titanic.close 服务必须回复 1 个帧，如下所示

  • 帧 0: 状态码（下文解释）

状态码必须是下文“状态帧”部分列出的代码之一。UUID 必须格式化为 32 个十六进制字符（'0' 到 '9' 以及 'A' 到 'Z' 或 'a' 到 'z'）。

titanic.close 服务是幂等的，如果 UUID 未知，必须返回“200 OK”。

请求执行

服务器通过在服务可用时将请求发送到经纪人来异步执行请求。TSP 不定义任何性能特性。

状态帧

来自 TSP 服务的每个回复都包含一个状态帧，后跟零个或多个内容帧。状态帧包含一个格式化为三个数字的字符串，可选地后跟一个空格和描述性文本。客户端不得以任何方式将文本视为重要信息。实现不得使用此处未定义的状态码

  • 200 - 正常 (OK)。TSP 服务成功执行了请求。对于 titanic.reply 服务，这还意味着“真实”服务执行成功。
  • 300 - 待处理 (PENDING)。客户端应该稍后重试该请求。
  • 400 - 未知 (UNKNOWN)。客户端正在使用无效或未知的 UUID，不应重试。
  • 500 - 错误 (ERROR)。由于某些内部错误，服务器无法完成请求。客户端应该稍后重试。

参考实现

指南第 4 章中的 C99 Titanic 示例（参见“ØMQ - 指南"）是 TSP 的主要参考实现。示例的翻译版本可能存在于其他语言中。