译文
原文链接 : https://nsq.io/clients/tcp_protocol_spec.html
The NSQ protocol is simple enough that building clients should be trivial in any language. We provide official Go and Python client libraries.
NSQ协议非常简单,在任何语言中构建客户机都是非常简单的。我们提供官方的Go和Python客户端库。
An nsqd
process listens on a configurable TCP port that accepts client connections.
一个“nsqd”进程监听一个可配置的TCP端口,该端口接受客户端连接。
After connecting, a client must send a 4-byte “magic” identifier indicating what version of the protocol they will be communicating (upgrades made easy).
连接之后,客户端必须发送一个4字节的“magic”标识符,指示他们将通信的协议版本(升级变得很容易)。
V2
(4-byte ASCII[space][space][V][2]
) a push based streaming protocol for consuming (and request/response for publishing)
v2(4字节的 ASCLL 结构师 【空格】【空格】【v】【2】)一种基于推送的流媒体协议,用于消费(和发布请求/响应)
After authenticating, the client can optionally send an IDENTIFY
command to provide custom metadata (like, for example, more descriptive identifiers) and negotiate features. In order to begin consuming messages, a client must SUB
to a channel.
经过身份验证后,客户端可以选择发送“IDENTIFY”命令来提供自定义元数据(例如,更多的描述性标识符)并协商特性。为了开始使用消息,客户端必须“SUB”到一个通道。
Upon subscribing the client is placed in a RDY
state of 0. This means that no messages will be sent to the client. When a client is ready to receive messages it should send a command that updates its RDY
state to some # it is prepared to handle, say 100. Without any additional commands, 100 messages will be pushed to the client as they are available (each time decrementing the server-side RDY
count for that client).
在订阅时,客户端处于' RDY '状态为0。这意味着不会向客户机发送任何消息。当客户机准备接收消息时,它应该发送一个命令,将其“RDY”状态更新到它准备处理的某个#,比如100。如果没有任何附加命令,100条消息将在可用时推送到客户机(每次减少该客户机的服务器端“RDY”计数)。
The V2 protocol also features client heartbeats. Every 30s (default but configurable), nsqd
will send a _heartbeat_
response and expect a command in return. If the client is idle, send NOP
. After 2 unanswered _heartbeat_
responses, nsqd
will timeout and forcefully close a client connection that it has not heard from. The IDENTIFY
command may be used to change/disable this behavior.
V2协议还具有客户端心跳功能。每30秒(默认但可配置),' nsqd '将发送一个' heartbeat '响应,并期待命令返回。如果客户端空闲,发送“NOP”。在两个未回复的“_heartbeat_”响应之后,“nsqd”将超时并强制关闭一个它没有收到消息的客户机连接。“IDENTIFY”命令可用于更改/禁用此行为。
Notes 注释
- Unless stated otherwise, all binary sizes/integers on the wire are network byte order (ie. big endian)
除非另有说明,网络上所有二进制大小/整数都是网络字节顺序(即:大尾数法,大端法)
- Valid topic and channel names are characters
[.a-zA-Z0-9_-]
and1 < length <= 64
(max length was32
prior tonsqd
0.2.28
)
有效的topic和channel名称是字符的[。a-zA-Z0-9_-]和' 1 < length <= 64 '(最大长度' 32 '先于' nsqd ' ' 0.2.28 ')
Commands 命令
IDENTIFY 识别
Update client metadata on the server and negotiate features
更新服务器上的客户机元数据并协商特性
IDENTIFY\n
[ 4-byte size in bytes ][ N-byte JSON data ]
NOTE: this command takes a size prefixed JSON body, relevant fields:
注意:该命令大小为前缀JSON 主题,相关字段:
- client_id an identifier used to disambiguate this client (ie. something specific to the consumer)
客户端编号用于消除此客户端的歧义的标识符(即。特定于消费者的东西)
- hostname the hostname where the client is deployed
主机名这个主机名用于客户机的部署
- feature_negotiation (
nsqd
v0.2.19+
) bool used to indicate that the client supports feature negotiation. If the server is capable, it will send back a JSON payload of supported features and metadata.
判断参数(
nsqd
v0.2.19+
) 判断用于指示客户端支持特性协商。如果服务器有能力,它将返回一个JSON负载,其中包含受支持的特性和元数据。
- heartbeat_interval (
nsqd
v0.2.19+
) milliseconds between heartbeats.
心跳间隔(
nsqd
v0.2.19+
) 毫秒比级别的心跳机制。
Valid range: 1000 <= heartbeat_interval <= configured_max
(-1
disables heartbeats)
--max-heartbeat-interval
(nsqd flag) controls the max
Defaults to --client-timeout / 2
有效范围:
1000 <= heartbeat_interval <= configured_max
(-1
禁用心跳)
--max-heartbeat-interval
(nsqd标志)控制最大值默认为
--client-timeout / 2
- output_buffer_size (
nsqd
v0.2.21+
) the size in bytes of the buffer nsqd will use when writing to this client.
输出缓冲区的大小 (
nsqd
v0.2.21+
) 写入此客户机时将使用缓冲区nsqd的字节大小。
Valid range: 64 <= output_buffer_size <= configured_max
(-1
disables output buffering)
--max-output-buffer-size
(nsqd flag) controls the max
Defaults to 16kb
有效范围:
64 <= output_buffer_size <= configured_max
(-1
禁用输出缓冲)
--max-output-buffer-size
(nsqd 标志) 控制最大值默认为
16kb
- output_buffer_timeout (
nsqd
v0.2.21+
) the timeout after which any data that nsqd has buffered will be flushed to this client.
输出缓冲区超时(
nsqd
v0.2.21+
) nsqd缓冲的任何数据超时之后都将刷新到此客户机。
Valid range: 1ms <= output_buffer_timeout <= configured_max
(-1
disables timeouts)
--max-output-buffer-timeout
(nsqd flag) controls the max
Defaults to 250ms
有效范围:
1ms <= output_buffer_timeout <= configured_max
(-1
禁用超时)
--max-output-buffer-timeout
(nsqd 标志) 控制最大值默认为
250ms
Warning: configuring clients with an extremely low (< 25ms
) output_buffer_timeout
has a significant effect on nsqd
CPU usage (particularly with > 50
clients connected).
警告:使用极低配值配置客户端 (
< 25ms
)output_buffer_timeout
对nsqd
cpu使用率有着显著影响 (特别是> 50
客户端链接 ).
This is due to the current implementation relying on Go timers which are maintained by the Go runtime in a priority queue. See the commit message in pull request #236 for more details.
这是由于当前的实现依赖于Go定时器,而Go定时器是由Go运行时在优先队列中维护的。参见pull request #236中的commit message。
- tls_v1 (
nsqd
v0.2.22+
) enable TLS for this connection.
tls_v1 (' nsqd ' ' v0.2.22+ ')为该连接启用TLS。
--tls-cert
and --tls-key
(nsqd flags) enable TLS and configure the server certificate
--tls-cert
和--tls-key
(nsqd标志)启用TLS并配置服务器证书
If the server supports TLS it will reply "tls_v1": true
如果服务器支持TLS,它将回复
"tls_v1": true
The client should begin the TLS handshake immediately after reading the IDENTIFY
response
客户端应在读取
IDENTIFY
响应后立即开始TLS握手
The server will respond OK
after completing the TLS handshake
服务器将在完成TLS握手后响应“OK”
- snappy (
nsqd
v0.2.23+
) enable snappy compression for this connection.
snappy (
nsqd
v0.2.23+
) 为该连接启用snappy压缩.
--snappy
(nsqd flag) enables support for this server side
--snappy
(nsqd标志)支持此服务器端
The client should expect an additional, snappy compressed OK
response immediately after the IDENTIFY
response.
客户端应该期望在
IDENTIFY
响应之后立即出现一个附加的、快速压缩的OK
响应。
A client cannot enable both snappy
and deflate
.
客户端不能同时启用
snappy
和deflate
。
- deflate (
nsqd
v0.2.23+
) enable deflate compression for this connection.
deflate (
nsqd
v0.2.23+
) 为该连接启用deflate压缩。
--deflate
(nsqd flag) enables support for this server side
--deflate
(nsqd标志)支持此服务器端
The client should expect an additional, deflate compressed OK
response immediately after the IDENTIFY
response.
客户端应该期望在“标识”响应之后立即出现一个附加的、压缩的“OK”响应。
A client cannot enable both snappy
and deflate
.
客户端不能同时启用
snappy
和deflate
。
- deflate_level (
nsqd
v0.2.23+
) configure the deflate compression level for this connection.
deflate_level (
nsqd
v0.2.23+
) 为该连接配置deflate压缩级别。.
--max-deflate-level
(nsqd flag) configures the maximum allowed value
Valid range: 1 <= deflate_level <= configured_max
Higher values mean better compression but more CPU usage for nsqd.
--max-deflate-level` (nsqd 标志) 配置允许的最大值
有效范围:
1 <= deflate_level <= configured_max
对于nsqd,更高的值意味着更好的压缩,但更多的CPU使用。
- sample_rate (
nsqd
v0.2.25+
) deliver a percentage of all messages received to this connection.
sample_rate (
nsqd
v0.2.25+
) 将接收到的所有消息的百分比发送到此连接。
Valid range: 0 <= sample_rate <= 99
(0
disables sampling)
Defaults to 0
有效范围:' 0 <= sample_rate <= 99 '(' 0 '禁用采样)
默认为' 0 '
- user_agent (
nsqd
v0.2.25+
) a string identifying the agent for this client in the spirit of HTTP
user_agent (
nsqd
v0.2.25+
) 一个字符串,它以HTTP的方式标识此客户机的代理
Default: <client_library_name>/<version>
默认: `<client_library_name>/<version>
- msg_timeout (
nsqd
v0.2.28+
) configure the server-side message timeout in milliseconds for messages delivered to this client.
msg_timeout (
nsqd
v0.2.28+
) 为发送到此客户机的消息配置服务器端消息超时(以毫秒为单位)。
Success Response:
成功返回:
OK
NOTE: if feature_negotiation
was sent by the client (and the server supports it) the response will be a JSON payload as described above.
注意:如果客户端发送了
feature_negotiation
(服务器支持它),响应将是上面描述的JSON有效负载。
Error Responses:
错误 返回:
E_INVALID
E_BAD_BODY
SUB
Subscribe to a topic/channel
订阅主题/频道
SUB <topic_name> <channel_name>\n
<topic_name> - a valid string (optionally having #ephemeral suffix)
<channel_name> - a valid string (optionally having #ephemeral suffix)
Success response:
成功返回:
OK
Error Responses:
错误 返回:
E_INVALID
E_BAD_TOPIC
E_BAD_CHANNEL
PUB
Publish a message to a topic:
向主题发布消息:
PUB <topic_name>\n
[ 4-byte size in bytes ][ N-byte binary data ]
<topic_name> - a valid string (optionally having #ephemeral suffix)
Success Response:
成功返回:
OK
Error Responses:
错误返回:
E_INVALID
E_BAD_TOPIC
E_BAD_MESSAGE
E_PUB_FAILED
MPUB
Publish multiple messages to a topic (atomically):
发布多个消息到一个主题(原子):
NOTE: available in nsqd
v0.2.16+
注:可用“nsqd”“v0.2.16+”
MPUB <topic_name>\n
[ 4-byte body size ]
[ 4-byte num messages ]
[ 4-byte message #1 size ][ N-byte binary data ]
... (repeated <num_messages> times)
<topic_name> - a valid string (optionally having #ephemeral suffix)
Success Response:
成功返回
OK
Error Responses:
错误返回
E_INVALID
E_BAD_TOPIC
E_BAD_BODY
E_BAD_MESSAGE
E_MPUB_FAILED
DPUB
Publish a deferred message to a topic:
将延迟消息发布到主题:
NOTE: available in nsqd
v0.3.6+
注:可用“nsqd”“v0.3.6+”
DPUB <topic_name> <defer_time>\n
[ 4-byte size in bytes ][ N-byte binary data ]
<topic_name> - a valid string (optionally having #ephemeral suffix)
<defer_time> - a string representation of integer D which defines the time for how long to defer where 0 <= D < max-requeue-timeout
Success Response:
OK
Error Responses:
E_INVALID
E_BAD_TOPIC
E_BAD_MESSAGE
E_DPUB_FAILED
RDY
Update RDY
state (indicate you are ready to receive N
messages)
更新“RDY”状态(表示您准备接收“N”消息)
NOTE: as of nsqd
v0.2.20+
use --max-rdy-count
to bound this value
注意:从
nsqd
v0.2.20+
use--max-rdy-count
开始绑定这个值
RDY <count>\n
<count> - a string representation of integer N where 0 < N <= configured_max
NOTE: there is no success response
注:没有成功响应
Error Responses:
E_INVALID
FIN
Finish a message (indicate successful processing)
完成一条消息(指示成功处理)
FIN <message_id>\n
<message_id> - message id as 16-byte hex string
NOTE: there is no success response
注:没有成功响应
Error Responses:
E_INVALID
E_FIN_FAILED
REQ
Re-queue a message (indicate failure to process)
重新队列消息(指示要处理的“失败”)
The re-queued message is placed at the tail of the queue, equivalent to having just published it, but for various implementation specific reasons that behavior should not be explicitly relied upon and may change in the future.
重新排队的消息被放置在队列的尾部,相当于刚刚发布了它,但是由于各种实现的特定原因,行为不应该被显式依赖,并且将来可能会发生变化。
Similarly, a message that is in-flight and times out behaves identically to an explicit REQ
.
类似地,正在运行和超时的消息的行为与显式的“REQ”相同。
REQ <message_id> <timeout>\n
<message_id> - message id as 16-byte hex string
<timeout> - a string representation of integer N where N <= configured max timeout
0 is a special case that will not defer re-queueing
NOTE: there is no success response
注:没有成功响应
Error Responses:
E_INVALID
E_REQ_FAILED
TOUCH
Reset the timeout for an in-flight message
重置飞行中消息的超时
NOTE: available in nsqd
v0.2.17+
TOUCH <message_id>\n
<message_id> - the hex id of the message
NOTE: there is no success response
注:没有成功响应
Error Responses:
E_INVALID
E_TOUCH_FAILED
CLS
Cleanly close your connection (no more messages are sent)
干净地关闭连接(不再发送消息)
CLS\n
Success Responses:
CLOSE_WAIT
Error Responses:
E_INVALID
NOP
No-op
无操作
NOP\n
NOTE: there is no response
注:没有响应
AUTH
NOTE: available in nsqd
v0.2.29+
注:可用
nsqd
v0.2.29+
If the IDENTIFY
response indicates auth_required=true
the client must send AUTH
before any SUB
, PUB
or MPUB
commands. If auth_required
is not present (or false
), a client must not authorize.
如果
IDENTIFY
响应指示auth_required=true
,客户端必须在任何SUB
、PUB
或MPUB
命令之前发送AUTH
。如果auth_required
不存在(或false
),客户端就不能授权。
When nsqd
receives an AUTH
command it delegates responsibility to the configured --auth-http-address
by performing an HTTP request with client metadata in the form of query parameters: the connection’s remote address, TLS state, and the supplied auth secret. See AUTH for more details.
当
nsqd
接收到AUTH
命令时,它通过以查询参数的形式使用客户机元数据执行HTTP请求,将责任委托给已配置的——AUTH - HTTP -address
,查询参数包括连接的远程地址、TLS状态和提供的AUTH秘密。更多信息请参见AUTH。
AUTH\n
[ 4-byte size in bytes ][ N-byte Auth Secret ]
Success Response:
成功返回
A JSON payload describing the authorized client’s identity, an optional URL and a count of permissions which were authorized.
描述授权客户端的标识、可选URL和授权的权限数的JSON有效负载。
{"identity":"...", "identity_url":"...", "permission_count":1}
Error Responses:
错误返回
E_AUTH_FAILED - An error occurred contacting an auth server
E_UNAUTHORIZED - No permissions found
Data Format
Data is streamed asynchronously to the client and framed in order to support the various reply bodies, ie:
数据是异步流到客户端和框架,以支持各种回复主体,即:
[x][x][x][x][x][x][x][x][x][x][x][x]...
| (int32) || (int32) || (binary)
| 4-byte || 4-byte || N-byte
------------------------------------...
size frame type data
A client should expect one of the following frame types:
客户端应该期望以下框架类型之一:
FrameTypeResponse int32 = 0
FrameTypeError int32 = 1
FrameTypeMessage int32 = 2
And finally, the message format:
最后,信息格式:
[x][x][x][x][x][x][x][x][x][x][x][x][x][x][x][x][x][x][x][x][x][x][x][x][x][x][x][x][x][x]...
| (int64) || || (hex string encoded in ASCII) || (binary)
| 8-byte || || 16-byte || N-byte
------------------------------------------------------------------------------------------...
nanosecond timestamp ^^ message ID message body
(uint16)
2-byte
attempts