19/FILEMQ
文件消息队列协议
- 状态：已淘汰
- 编辑：Pieter Hintjens ph@imatix.com
文件消息队列协议 (FILEMQ) 管理‘客户端’与‘服务器’之间的文件传输。FILEMQ 运行在 ZeroMQ 的 ZMTP 协议之上。
许可证
版权所有 (c) 2009-2012 iMatix Corporation
本规范是自由软件；您可以根据自由软件基金会发布的 GNU 通用公共许可证条款重新分发和/或修改它；可以选择许可证的第 3 版或任何更高版本。
分发本规范是希望它有用，但不作任何担保；不包括适销性或特定用途适用性的默示担保。有关详细信息，请参阅 GNU 通用公共许可证。
您应该已经随本程序收到了 GNU 通用公共许可证的副本；如果没有，请参阅 https://gnu.ac.cn/licenses。
变更流程
本规范是一个自由开放的标准（参见“自由开放标准的定义”）并受数字标准组织（Digital Standards Organization）的共识导向规范系统（COSS）管辖（参见“共识导向规范系统”）。
语言
本文档中的关键词“MUST”（必须）、“MUST NOT”（不得）、“REQUIRED”（要求）、“SHALL”（应）、“SHALL NOT”（不应）、“SHOULD”（应该）、“SHOULD NOT”（不应）、“RECOMMENDED”（推荐）、“MAY”（可以）和“OPTIONAL”（可选）应按 RFC 2119 中的描述进行解释（参见“RFC 中用于指示要求级别的关键词”）。
目标
FILEMQ 协议定义了一种使用发布-订阅模式进行广域文件分发机制。其目标包括：
- 允许客户端“订阅”服务器托管的目录，而无需提前得知这些目录中将创建哪些文件。
- 向客户端提供高速分块文件传输。
- 允许客户端任意取消和重新启动文件传输。
- 实现完全安全。
实现
形式语法
以下 ABNF 语法定义了 FILEMQ 协议：
filemq-protocol = open-peering *use-peering [ close-peering ]
open-peering = C:OHAI *( S:ORLY C:YARLY ) ( S:OHAI-OK / error )
use-peering = C:ICANHAZ ( S:ICANHAZ-OK / error )
/ C:NOM
/ S:CHEEZBURGER
/ C:HUGZ S:HUGZ-OK
/ S:HUGZ C:HUGZ-OK
close-peering = C:KTHXBAI / S:KTHXBAI
error = S:SRSLY / S:RTFM
; The client opens peering to the server
OHAI = signature %x01 protocol version
signature = %xAA %xA3
protocol = string ; Must be "FILEMQ"
string = size *VCHAR
size = OCTET
version = %x01
; The server challenges the client using the SASL model
ORLY = signature %x02 mechanisms challenge
mechanisms = size 1*mechanism
mechanism = string
challenge = *OCTET ; ZeroMQ frame
; The client responds with SASL authentication information
YARLY = %signature x03 mechanism response
response = *OCTET ; ZeroMQ frame
; The server grants the client access
OHAI-OK = signature %x04
; The client subscribes to a virtual path
ICANHAZ = signature %x05 path options cache
path = string ; Full path or path prefix
options = dictionary
dictionary = size *key-value
key-value = string ; Formatted as name=value
cache = dictionary ; File SHA-1 signatures
; The server confirms the subscription
ICANHAZ-OK = signature %x06
; The client sends credit to the server
NOM = signature %x07 credit
credit = 8OCTET ; 64-bit integer, network order
; The server sends a chunk of file data
CHEEZBURGER = signature %x08 sequence operation filename
offset headers chunk
sequence = 8OCTET ; 64-bit integer, network order
operation = create | delete
create = %x01 ; Octet
delete = %x02 ; Octet
filename = string
offset = 8OCTET ; 64-bit integer, network order
headers = dictionary
chunk = FRAME
; Client or server sends a heartbeat
HUGZ = signature %x09
; Client or server responds to a heartbeat
HUGZ-OK = signature %x0A
; Client closes the peering
KTHXBAI = signature %x0B
; Server error reply - refused due to access rights
S:SRSLY = signature %x80 reason
reason = string
; Server error reply - client sent an invalid command
S:RTFM = signature %x81 reason
互连模型
ZeroMQ 套接字类型
服务器应创建一个 ROUTER 套接字，并应将其绑定到端口 5670，这是互联网号码分配局 (IANA) 为 FILEMQ 注册的端口。服务器可以将其 ROUTER 套接字绑定到临时端口范围 (%C000x - %FFFFx) 内的其他端口。客户端应创建一个 DEALER 套接字，并将其连接到服务器 ROUTER 的主机和端口。
请注意，ROUTER 套接字会为调用者提供在套接字上收到的任何消息的发送方连接身份，作为消息中其他帧之前的身份帧。
协议签名
每个 ZeroMQ 消息应以 FILEMQ 协议签名 %xAA %xA3 开头。服务器和客户端应静默丢弃收到的任何不以这两个字节开头的数据。
此机制专门设计用于绑定到临时端口的服务器，这些端口可能之前已被其他协议使用过，并且仍有对等方尝试连接到它们。它也是一种通用的快速失败机制，用于检测格式错误的消息。
连接状态
服务器应使用 RTFM 命令回复意外的命令。客户端应在收到 RTFM 命令后关闭其 DEALER 连接并启动新连接。
FILEMQ 命令
OHAI 命令
客户端应通过向服务器发送 OHAI 命令来启动新连接。此命令标识协议和版本。这是为了允许进行版本检测。
如果服务器不支持请求的协议版本，应回复 RTFM 命令。客户端可以尝试使用较低的协议版本再次连接。
如果服务器接受 OHAI 命令，应回复 OHAI-OK 命令；如果需要认证，则回复 ORLY 命令。
ORLY 命令
当客户端请求访问时，服务器可以使用 ORLY 命令回复，以启动简单认证和安全层 (SASL) 的质询与响应交换。服务器应提供其接受的机制列表，以及包含质询的二进制数据帧。
YARLY 命令
客户端应该使用包含计算出的响应数据的 YARLY 命令来响应 ORLY 命令。请注意，SASL 质询/响应模型使用外部 SASL 库来处理质询数据并返回适当的响应数据。
客户端或服务器必须至少支持 SASL 的“PLAIN”机制。
OHAI-OK 命令
当服务器在 OHAI 或 YARL 命令后授予客户端访问权限时，应回复 OHAI-OK 命令。如果服务器不授予访问权限，应回复 SRSLY 命令。
ICANHAZ 命令
客户端可以通过向服务器发送 ICANHAZ 命令来订阅任意数量的虚拟路径。客户端可以指定完整路径，也可以指定部分路径，部分路径用作前缀匹配。路径必须以“/”开头，因此路径“/”订阅所有内容。
‘路径’不必存在于服务器上。也就是说，客户端可以请求将来可能存在于服务器上的路径。
‘选项’字段向服务器提供额外信息。服务器应该实现以下选项：
- RESYNC=1- 如果客户端设置此选项，服务器应将虚拟路径的全部内容发送给客户端，但客户端已有的文件除外，这些文件由其在‘缓存’字段中的 SHA-1 摘要标识。
当客户端指定 RESYNC 选项时，‘缓存’字典字段告诉服务器客户端已经有哪些文件。‘缓存’字典中的每个条目都是一个“文件名=摘要”的键/值对，其中摘要应是可打印十六进制格式的 SHA-1 摘要。如果文件名以‘/’开头，则应该以路径开头，否则服务器必须忽略它。如果文件名不以‘/’开头，则服务器应将其视为相对于路径。
ICANHAZ-OK 命令
当服务器接受订阅时，必须回复 ICANHAZ-OK 命令。如果服务器拒绝订阅，应回复 SRSLY 命令，并丢弃来自该客户端的所有后续命令。
NOM 命令
客户端必须通过向服务器发送信用（配额）来启动数据传输。服务器应仅向客户端发送其拥有信用额度内的数据量。信用是以字节为单位的数量，对应于实际文件内容（但不包括命令本身使用的字节）。
客户端可以在收到服务器的 OHAI-OK 后随时发送 NOM 命令。服务器不应直接响应 NOM 命令。
CHEEZBURGER 命令
服务器应使用 CHEEZBURGER 命令向客户端发送文件内容。每个 CHEEZBURGER 命令应发送文件数据的一个块，从特定偏移量开始。服务器必须将单个文件的内容作为连续的数据块发送，客户端可以依赖此行为。
headers 字段保留供将来使用。
HUGZ 命令
服务器或客户端可以在服务器向客户端发送 OHAI-OK 后（并且客户端已收到）随时发送心跳命令。
HUGZ 命令用作心跳，表明对等方处于活动状态。服务器和客户端应将来自对等方的任何命令视为对等方处于活动状态的信号。
因此，对等方可以选择仅在未向另一对等方发送任何其他流量时才向其发送 HUGZ。
HUGZ-OK 命令
对等方应使用 HUGZ-OK 命令响应 HUGZ 命令。这使得一个对等方可以负责所有的心跳机制。
KTHXBAI 命令
客户端可以通过向服务器发送 KTHXBAI 命令来结束连接。服务器不应响应此命令。
SRSLY 命令
服务器应使用 SRSLY 命令响应任何失败的尝试访问服务器资源的请求。这包括失败的认证和失败的订阅。当客户端收到 SRSLY 命令时，应该关闭连接，并在需要时使用新的认证凭据重新连接。
RTFM 命令
服务器应通过发送 RTFM 来响应无效命令。请注意，服务器不应向发送无效协议签名的客户端发送 RTFM。当客户端收到 RTFM 命令时，应该关闭连接，并且不重新连接。
安全方面
FILEMQ 使用简单认证和安全层 (SASL) 进行认证和加密。用于文件缓存标识的 SHA-1 摘要没有安全隐患。