NSQ-TCP协议说明

博主： xiongmao
发布时间：2021 年 02 月 24 日
17206次浏览
2625字数
分类： Nsq

译文

原文链接： 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 IDENTIFYcommand 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_-] and 1 < length <= 64 (max length was 32prior to nsqd 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对 nsqdcpu使用率有着显著影响 (特别是 > 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 IDENTIFYresponse.

客户端应该期望在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 IDENTIFYresponse.

客户端应该期望在“标识”响应之后立即出现一个附加的、压缩的“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 MPUBcommands. 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

最后修改：2021 年 02 月 24 日 08 : 23 AM

如果觉得我的文章对你有用，请随意赞赏

热门文章
随机文章

NSQ—DOCKER
浏览次数: 18220
人工智障-go语言实现核心代码估价一个小目标
浏览次数: 17344
NSQ-TCP协议说明
浏览次数: 17207
NSQ管理
浏览次数: 16138
NSQ内部组件
浏览次数: 14397

第四天
浏览次数: 204
2021年2月25日
浏览次数: 3772
NSQ的性能
浏览次数: 2466
2021年8月23日-8月27日周总结
浏览次数: 1827
关于设计模式用go复习一下
浏览次数: 287

NSQ-TCP协议说明

xiongmao • 2021 年 02 月 24 日

译文

原文链接： 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】）一种基于推送的流媒体协议，用于消费(和发布请求/响应)

经过身份验证后，客户端可以选择发送“IDENTIFY”命令来提供自定义元数据(例如，更多的描述性标识符)并协商特性。为了开始使用消息，客户端必须“SUB”到一个通道。

在订阅时，客户端处于' RDY '状态为0。这意味着不会向客户机发送任何消息。当客户机准备接收消息时，它应该发送一个命令，将其“RDY”状态更新到它准备处理的某个#，比如100。如果没有任何附加命令，100条消息将在可用时推送到客户机(每次减少该客户机的服务器端“RDY”计数)。

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_-] and 1 < length <= 64 (max length was 32prior to nsqd 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对 nsqdcpu使用率有着显著影响 (特别是 > 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 IDENTIFYresponse.

客户端应该期望在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 IDENTIFYresponse.

客户端应该期望在“标识”响应之后立即出现一个附加的、压缩的“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)

重新队列消息(指示要处理的“失败”)

重新排队的消息被放置在队列的尾部，相当于刚刚发布了它，但是由于各种实现的特定原因，行为不应该被显式依赖，并且将来可能会发生变化。

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+

如果 IDENTIFY 响应指示 auth_required=true ，客户端必须在任何 SUB 、PUB或MPUB命令之前发送AUTH。如果auth_required不存在(或false)，客户端就不能授权。

当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