beanstalkd

协议

描述

beanstalkd 协议 运行在 TCP 层上，并采用了 ASCII 编码。
大致工作流程为：开启客户端连接、发送命令和数据、等待响应、关闭连接。
对于每一个连接而言，服务器会按照接收到指令的顺序一一执行这些指令，并且按照同样的顺序，发送响应。
在本协议中，所有涉及到的整数，都是指十进制，且为非负，除非另有说明。

命名约定

只支持 ASCII 字符进行命名
其支持的字符有：

• 字母（ A-Z、a-z ）
• 数字（ 0-9 ）
• 小短横（ - ）
• 加号（ + ）
• 正斜杠（ / ）
• 英文封号（ ; ）
• 英文点号（ . ）
• 美元符（ $ ）
• 英文下划线（ _ ）
• 英文左右小括号（ “(“ 和 “)” ）

  注意：命名不可以 - 作为开头，当遇到空格或换行时，会视作命名结束。每个命名的长度，至少为 1+ 个字符。

Errors

Job 生命周期

一个 Job 由 put 命令创建，在它的生命周期以内，它必将处于以下四种状态中的一种：「ready」、「reserved」、「delayed」、「buried」
当使用完 put 命令，Job 一般从 「ready」 开始，它会在「ready」队列中等待，直到有「reserved」命令过来，当接收成功之后，则将该 Job 放入到 「reserved」 队列。接着，当进程处理完这个 Job 之后，则会发送一个「delete」命令，将这个 Job 从 beanstalkd 中删除。

图示 Job 生命周期：

put            reserve               delete
  -----> [READY] ---------> [RESERVED] --------> *poof*

当然，它也可能经历更复杂的演化，如下图：

put with delay               release with delay
  ----------------> [DELAYED] <------------.
                        |                   |
                 kick   | (time passes)     |
                        |                   |
   put                  v     reserve       |       delete
  -----------------> [READY] ---------> [RESERVED] --------> *poof*
                       ^  ^                |  |
                       |   \  release      |  |
                       |    `-------------'   |
                       |                      |
                       | kick                 |
                       |                      |
                       |       bury           |
                    [BURIED] <---------------'
                       |
                       |  delete
                        `--------> *poof*

Tubes

一个 beanstalkd 服务允许拥有多个 Tube ，每一个 Tube 包含两个队列： ready queue 和 delay queue 。
每个 Job 都必然会存在于某个 Tube 之下。
可以通过 watch 指令关注某个 Tube ，也可以通过 ignore 命令取消关注。
当你使用 watch list 命令时，它会返回你所关注的 tubes 。
当消费者开始接收 Job 的时候，Job 一般来自 watch 了的 Tube。
当一个客户端连接进来，watch list 最初只有一个名为 default 的 tube 。如果当存入 Job 时没有使用 use 命令指定 tube ，这个 Job 就会被放入到 default tube 中。
Tubes 会在你使用到它的时候创建，如果 Tube 变空了（没有 ready Job ，没有 delayed Job ， 没有 buried Job），且没有客户端连接指向它，它就会被删掉。

命令

生产者命令

put

此命令用于向队列中插入 job ，命令格式如下：

put <pri> <delay> <ttr> <bytes>\r\n
<data>\r\n

它默认会将 job 插入到当前所 use 的 tube ， 这点可以参考下面的 use命令

当成功发送 put 命令后，客户端要等待响应，响应结果可能是如下几个：

use

此命令为 Producer 提供，当发送此命令之后，后续的 put 命令，就会把 job 全部放入到此 use 命令指定的 tube 中。如果没有通过 use 指定 tube ， 则会默认将 job 放入到 default tube 中。

use <tube>\r\n

消费者命令

从 queue 中消费 job 会使用以下命令：

• reserve
• delete
• release
• bury

  reserve

  reserve\r\n

  另外，你还能指定接收的超时时间，如下：

  reserve-with-timeout <seconds>\r\n

  这个命令将会返回一个新的、reserved 状态的 job
  如果没有可用的 job 能被接收，则 beanstalkd 一直等到出现一个可接收的 job 之后再返回。
  一旦一个 job 被客户端接收，客户端要在 ttr 指定的时间限定内处理 job ，否则，超时的话，服务器会将 job 重新放回 ready queue 中。
  可以在 stats-job 命令的 response 中找到 ttr 的值和已经使用掉的时间。
  如果处于 ready 状态的 job 不止一个，beanstalkd 将会选择一个 priority 最小的 job，如果 priority 相等，则会选择一个最先 put 的 job 。

  题外话：这里我怀疑 beanstalkd 的协议有一处写错了，原文为 Within each priority, it will choose the one that was reserved first. 我认为应该将 reserved 改为 put 。

如果指定的 timeout seconds 是 0 ，这将导致服务器立即返回 TIME_OUT 的响应（也有可能立即返回一个 job ，这取决于服务器的响应速度以及是否存在可接收的 job ）
为 timeout 设置一个合理的 seconds ，可以限制客户端阻塞等待接收 job 的时间。

成功响应：

RESERVED <id> <bytes>\r\n
<data>\r\n

delete

delete 命令用于从服务器完全删除一个 job ， 这一般用于客户端成功处理 job 之后。
客户端可以删除 reserved 的 job ， 使 job 进入准备状态 ， 延迟 job ，预留 job 。

delete <id>\r\n

release

此命令可以把 reserved job 放回 ready 队列中，同时 job 的状态也会回到 ready ，release 之后，这个 job 可以被任何其他的客户端接收。
一般这个命令用在消费者处理 job 失败的情况下。

release <id> <pri> <delay>\r\n

bury

这个命令可以将一个 job 操作为 buried 状态。
buried job 被存放在一个 FIFO （first input first out ，先进先出）的链表中，它不会被服务器再次操作，除非有客户端对它发起了 kick 命令。

bury <id> <pri>\r\n

touch

此命令能让当前消费者得到更多的执行 job 的时间。
比如，ttr 是用于避免消费者崩溃而导致 job 丢失，但同样也会误伤一批执行时间过长的消费者，实际上消费者没有崩溃，但执行时间已经超出了 ttr ，此时，通过 touch 命令，可以让客户端得到更多的处理时间，不先触发 ttr 机制。
当然，使用了 touch 命令，只是延长了 ttr 的时间，ttr 的机制仍然存在。
通过这个命令，消费者可以定期告诉服务器，当前处理程序仍处于活跃状态。
此命令不受 DEADLINE_SOON影响

touch <id>\r\n

watch

watch 命令会往 watch list 中添加一个 tube ，消费者通过 reserve ，可以接收到 watch list 中任何一个 tube 传来的 job 。一个新的连接，watch list 中默认存在一个 default tube 。

watch <tube>\r\n

返回响应：

WATCHING <count>\r\n

conut 是一个数值，指当前 watch list 中有多少 tube 。

ignore

此命令用于从 watch list 中移除一个 tube ，移除之后，该消费者不再接收被移除的 tube 内的 job 。

ignore <tube>\r\n

成功响应：

WATCHING <count>\r\n

conut 是一个数值，指当前 watch list 中有多少 tube 。

其他命令

peek

用于客户端检查 job ，此命令有四种形态，除了第一个操作以外，其它操作都只针对于当前的 tube 。

peek <id>\r\n 根据 id 返回一个 job
peek-ready\r\n 返回下一个 ready job
peek-delayed\r\n 返回下一个剩余延迟时间最短的 delayed job
peek-buried\r\n 返回下一个 buried job

成功响应：

FOUND <id> <bytes>\r\n
<data>\r\n

其中，id 为 job 的 id ，bytes 指 data 的大小（不包含 \r\n ），data 是 job 的具体内容

kick

此命令只适用于当前指定的 tube 。
此命令能将 job 状态改成 ready ， 它需要传入一个数字，用于指定需要修改多少个 job 。
比如，你传入 10 ，则会将队列中十个 buried 或 delayed 状态的 job ，修改为 ready 。
如果，指定的队列中存在 buried job ，则只会修改 buried job，否则，就修改 delayed job 。

kick <bound>\r\n

响应：

KICKED <count>\r\n

count 表示该操作成功修改了几个 job 。

kick-job

这是一个 kick 扩展命令，用于将单独的一个 job 修改为 ready 。它需要传入一个 job id 。
如果传入的 job id 所代表的 job 在当前 tube 中存在，并且该 job 的状态处于 buried 或 delayed ，则会将这个 job 设置为 ready ，并仍然在当前 tube 中。

kick-job <id>\r\n

stats-job

此命令用于查看一个 job 的统计信息

stats-job <id>\r\n

成功响应：

OK <bytes>\r\n
<data>\r\n

bytes 指后面 data 的大小，data 则是该 job 的统计信息，是一个 YAML 格式的文本。
data 包含以下 key ：

stats-tube

此命令返回 tube 的统计信息，如果这个 tube 存在的话。

stats-tube <tube>\r\n

成功响应：

OK <bytes>\r\n
<data>\r\n

bytes 是指 data 的大小，不包含 「\r\n」。
data 是一个 YAML 格式的文本，它包含了你想要的 tube 的统计信息
下面是 data 的 key ：

stats

此命令返回整个服务器系统的统计信息。

stats\r\n

成功响应：

OK <bytes>\r\n
<data>\r\n

bytes 是指 data 的大小，但不包括 「\r\n」。
data 是一个 YAML 文本，包含了如下 key ：

上面这些 key 的信息，自从 beanstalkd 启动以来就开始累积，如果重启，就会重新累积。另外，这些数据不存放在 binlog 中

list-tubes

此命令返回所有存在的 tube 。

list-tubes\r\n

成功响应：

OK <bytes>\r\n
<data>\r\n

bytes 是指 data 的大小，不包含「\r\n」。
data 返回一个 YAML 字符串，里面包含了 tube 的列表。

list-tube-used

此命令返回当前所 use 的 tube 。

list-tube-used\r\n

成功响应：

USING <tube>\r\n

tube 是指当前 use 的 tube 名字。

list-tubes-watched

此命令用于查看当前客户端 watch-list 中的 tube 。

list-tubes-watched\r\n

成功响应：

OK <bytes>\r\n
<data>\r\n

bytes 是指 data 的大小，不包含「\r\n」。
data 是一个包含了 tube list 的 YAML 字符串。

quit

此命令用于关闭当前连接。

quit\r\n

pause-tube

此命令为某个 tube 指定一个时间，在这个时间内，此 tube 内的 job 将不会被 reserve 。

pause-tube <tbe-name> <delay>\r\n