Beanstalkd中文协议解读

  1. 错误说明
  2. job的生命周期

此版本已经合并到了Beanstalkd主仓库,你再也不用担心语言障碍了:https://github.com/kr/beanstalkd/blob/master/doc/protocol.zh-CN.md

这篇文档的另外一个版本:来自PHPBoy http://www.phpboy.net/2014-09/45-benstalkd-protocol.html

最近有需求做全平台的定时器,业务复杂,性能要求高,linux crontab的方式不适用,调研一些支持定时执行的内存队列系统,其中beanstalkd较适合。先将其协议研究一遍,使用就不是问题了。

###总括

beanstalkd协议基于ASCII编码运行在tcp上。客户端连接服务器并发送指令和数据,然后等待响应并关闭连接。对于每个连接,服务器按照接收命令的序列依次处理并响应。所有整型值都非负的十进制数,除非有特别声明。

###名称约定

所有名称必须是ASCII码字符串,即包括:

注意:名称不能以连字符开始,并且是以空白字符结束,每个名称至少包含一个字符。

错误说明

返回的错误 描述
OUT_OF_MEMORY\r\n 服务器没有足够的内存分配给特定的job,客户端应该稍后重试
INTERNAL_ERROR\r\n 服务器内部错误,该错误不应该发生,如果发生了,请报告:http://groups.google.com/group/beanstalk-talk.
BAD_FORMAT\r\n 格式不正确,客户端发送的指令格式出错,有可能不是以\r\n结尾,或者要求整型值等等
UNKNOWN_COMMAND\r\n 未知的命令,客户端发送的指令服务器不理解

job的生命周期

一个工作任务job当client使用put命令时创建。在整个生命周期中job可能有四个工作状态:ready,reserved,delayed,buried。在put之后,一个job的典型状态是ready,在ready队列中,它将等待一个worker取出此job并设置为其为reserved状态。worker占有此job并执行,当job执行完毕,worker可以发送一个delete指令删除此job。

Status Description
ready 等待被取出并处理
reserved 如果job被worker取出,将被此worker预订,worker将执行此job
delayed 等待特定时间之后,状态再迁移为ready状态
buried 等待唤醒,通常在job处理失败时

job典型的生命周期

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

job可能的状态迁移

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

###Tubes
一个服务器有一个或者多个tubes,用来储存统一类型的job。每个tube由一个就绪队列与延迟队列组成。每个job所有的状态迁移在一个tube中完成。consumers消费者可以监控感兴趣的tube,通过发送watch指令。consumers消费者可以取消监控tube,通过发送ignore命令。通过watch list命令返回所有监控的tubes,当客户端预订一个job,此job可能来自任何一个它监控的tube。

当一个客户端连接上服务器时,客户端监控的tube默认为defaut,如果客户端提交job时,没有使用use命令,那么这些job就存于名为default的tube中。

tube按需求创建,无论他们在什么时候被引用到。如果一个tube变为空(即no ready jobs,no delayed jobs,no buried jobs)和没有任何客户端引用,它将会被自动删除。

####指令说明(Commands)

####生产者指令说明(Producer Commands)

####put

插入一个job到队列

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

响应

INSERTED <id>\r\n

表示插入job成功,id为新job的任务标识,整型值

BURIED <id>\r\n

如服务器为了增加队列的优先级而,内存不足时返回,id为新job的任务标识,整型值

EXPECTED_CRLF\r\n

job body必须以\r\n结尾

JOB_TOO_BIG\r\n

job body的长度超过max-job-size

DRAINING\r\n

表示服务器资源耗尽,表示服务器已经进入了“drain mode”,服务器再也不能接受连接,客户端应该使用另一个服务器或者断开稍后重试

####use
说明
producer生产者使用,随后使用put命令,将job放置于对应的tube
格式

use <tube>\r\n
tube tube的名称,最大为200字节,不存在时将自动创建

响应

USING <tube>\r\n tube为正在使用的tube名称

消费者指令说明(Worker Commands)

####reserve
说明
取出(预订)job,待处理。它将返回一个新预订的job,如果没有job,beanstalkd将直到有job时才发送响应。一旦job状态迁移为reserved,取出job的client被限制在指定的时间(如果设置了ttr)完成,否则超时,job状态重装迁移为ready。
格式

reserve\r\n

可选的一个相似的命令
reserve-with-timeout \r\n 设置取job的超时时间,timeout设置为0时,服务器立即响应或者TIMED_OUT,积极的设置超时,将会限制客户端阻塞在取job的请求的时间。

#####失败响应

DEADLINE_SOON\r\n

在一个预定的任务的运行时间内,最后一秒会被服务器保持为一个安全边际,在此期间,客户端将无法等候另外一个任务。
如果客户端在安全隔离期间发出一个预留命令,或者安全隔离期到了,客户端在等候一个预定命令。

TIMED_OUT\r\n 超时

#####成功响应

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

成功取出job,id为job id,整型值,job body的长度,不包含\r\n,data为job body

####delete
说明
从队列中删除一个job
格式

delete <id>\r\n

id为job id
响应
DELETED\r\n 删除成功
NOT_FOUND\r\n job不存在时,或者job的状态不为ready和buried(这种情况是在job执行超时之前,client发送了delete指令)

####release
说明
release指令将一个reserved的job放回ready queue。它通常在job执行失败时使用。
格式

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

id 为job id,pri为job的优先级,delay为延迟ready的秒数
响应
RELEASED\r\n 表明成功
BURIED\r\n 如服务器为了增加队列的优先级而,内存不足时返回
NOT_FOUND\r\n 如果job不存在或者client没有预订此job

####bury
说明
将一个job的状态迁移为buried,通过kick命令唤醒
格式

bury <id> <pri>\r\n

id为job id,pri为优先级
响应
BURIED\r\n 表明成功
NOT_FOUND\r\n 如果job不存在或者client没有预订此job

####touch
说明
允许worker请求更多的时间执行job,这个很有用当job需要很长的时间来执行,worker可用周期的告诉服务器它仍然在执行job(可以被DEADLINE_SOON触发)
格式

touch <id>\r\n

id为job id
响应
TOUCHED\r\n 表明成功
NOT_FOUND\r\n 如果job不存在或者client没有预订此job

####watch
说明
添加监控的tube到watch list列表,reserve指令将会从监控的tube列表获取job,对于每个连接,监控的列表默认为default
格式

watch <tube>\r\n

tube 为监控的tube名称,名称最大为200字节,如果tube不存在会自动创建
响应

WATCHING <count>\r\n 表明成功

count 整型值,已监控的tube数量

####ignore
说明
从已监控的watch list列表中移出特定的tube
格式

ignore <tube>\r\n

tube 为移出的tube名称,名称最多为200字节,如果tube不存在会自动创建
响应

WATCHING <count>\r\n 表明成功

count 整型值,已监控的tube数量
NOT_IGNORED\r\n 如果client企图忽略其仅有的tube时的响应
其他指令说明(Other Command)

####peek
说明
让client在系统中检查job,有四种形式的命令,其中第一种形式的指令是针对当前使用的tube
格式

peek <id>\r\n  返回id对应的job
peek-ready\r\n 返回下一个ready job
peek-delayed\r\n 返回下一个延迟剩余时间最短的job
peek-buried\r\n 返回下一个在buried列表中的job

响应
NOT_FOUND\r\n 如果job不存在,或者没有对应状态的job

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

id 为对应的job id
bytes job body的字节数
data 为job body

####kick
说明
此指令应用在当前使用的tube中,它将job的状态迁移为ready或者delayed
格式

kick <bound>\r\n

bound 整型值,唤醒的job上限

响应

KICKED <count>\r\n

count 为真实唤醒的job数量
kick-job
说明
kick指令的一个变体,可以使单个job被唤醒,使一个状态为buried或者delayed的job迁移为ready,所有的状态迁移都在相同的tube中完成
格式

kick-job <id>\r\n

id 为job id
响应
NOT_FOUND\r\n 如果job不存在,或者job是不可唤醒的状态
KICKED\r\n 表明成功

####stats-job
说明
统计job的相关信息
格式

stats-job <id>\r\n

id 为job id
响应

NOT_FOUND\r\n 如果job不存在

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

bytes 为接下来的data区块的长度
data 为YAML file的统计信息
其中YAML file包括的key有:

####stats-tube
说明
统计tube的相关信息
格式

stats-tube <tube>\r\n

tube 为对应的tube的名称,最多为200字节
响应

NOT_FOUND\r\n 如果tube不存在
OK <bytes>\r\n<data>\r\n

bytes 为接下来的data区块的长度
data 为YAML file的统计信息
其中YAML file包括的key有:

####stats
说明
返回整个消息队列系统的整体信息
格式

stats\r\n

响应

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

bytes 为接下来的data区块的长度
data 为YAML file的统计信息
其中YAML file包括的key有(所有的信息都累积的,自从beanstalkd进程启动以来,这些信息不储存在binlog中):

####list-tubes
说明
列表所有存在的tube
格式

list-tubes\r\n

响应

OK <bytes>\r\n

<data>\r\n

bytes 为接下来的data区块的长度
data 为YAML file,包含所有的tube名称

####list-tube-used
说明
列表当前client正在use的tube
格式

list-tube-used\r\n

响应

USING <tube>\r\n

tube 为tube名称

####list-tubes-watched
说明
列表当前client watch的tube
格式

list-tubes-watched\r\n

响应

OK <bytes>\r\n

<data>\r\n

bytes 为接下来的data区块的长度
data 为YAML file,包含所有的tube名称

####quit
说明
关闭连接
格式

quit\r\n

####pause-tube

#####说明
此指令针对特定的tube内所有新的job延迟给定的秒数

#####格式

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

#####响应

PAUSED\r\n 表示成功
NOT_FOUND\r\n tube不存在

原创翻译,英文能力此水平,见谅。By PHPboy.

####英文版

https://github.com/kr/beanstalkd/blob/master/doc/protocol.md

script>