一、BeanstalkD协议

Beanstalk协议使用ASCII编码，运行在TCP协议之上。客户端负责主动建立连接，发送命令和数据，等待响应以及关闭连接。对于每个连接，服务端以接收请求的顺序串行地处理命令，并按相同的顺序发送响应。协议中所有的数字都是十进制并且非负的（除非有明确说明）。

协议中的名字都是ASCII字符串。名字可以包含字母（A-Z和a-z）、 数字（0-9）、连字符（”-“）、 加（”+”）、 斜线（”/”）、 分号（”;”）、 点（”.”）、 美元符号（”$”）、下划线（”_”）和括号（“(”和”)”），但是不能以连字符开头。名字以空格或换行结束。每个名字至少要有一个字符的长度。

协议中包含两类数据：文本行和非结构化的块数据。文本行用来传输客户端的命令和服务端的响应。块数据用来传输job体和统计信息。每个job体是一个不透明的字节序列。服务端从不检查或修改job体，直接按其原有的格式返回。job体的解释是有客户端来进行的。

当不再需要使用服务端时，客户端可以选择发送 ”quit” 命令或直接关闭TCP连接。然而，beanstalkd可以很好处理和维护大量打开的连接，所以，客户端应该尽可能包括连接的打开和重用。这同样也可以省去建立TCP连接的开销。

如果客户端违背了协议（比如发送错误格式的请求或者不存在的命令）或者服务端出错，服务端将返回下面信息的一种

• OUT_OF_MEMORY：表示服务端不能为job分配足够的内存。客户 端应该稍后重试。
• INTERNAL_ERROR：表示服务端的bug。这种情况不应该发生。如果 发生了，可以报给

  http://groups.google.com/group/beanstalk-talk。

• BAD_FORMAT：表示客户端发送了一个错误格式的命令行。可能呢 导致这种错误发生的情况有：行没有以\r\n结尾、在需要整数的地方出现了非数字字符、参数的数目错误、或者其他格式的命令行错误。
• UNKNOWN_COMMAND：表示客户端发送了一个服务端不认识的 命令。  这些错误响应不会在本文以下各节的命令列出，但都隐含在所有命令的说明里。客户端在发送命令之后都要准备好接收错误响应。  最后，如果服务端发生了严重的错误不能继续服务，服务端将会主动关闭连接。

 二、Producer命令

2.1 put

put命令用来向队列中插入一个job，包括一个命令行和一个job体：

Tips 01 : beanstalkd没有命令行，但可以使用 telnet，执行命令

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

put 命令将向客户端现在正在使用的tube中插入一个job（use命令见下文）。

• <pri> 是一个小于2*32的整数。小优先级数值的job将会排在大优先级 数值的job前面执行。最高优先级是0，最低优先级是4,294,967,295。
• <delay> 是一个整形数，表示将job放入ready队列需要等待的秒数。
• <ttr> time to run的简称，是一个整形数，表示允许一个worker执行该job的秒数。这个时间将从一个worker 获取一个job开始计算。如果该worker没能在<ttr> 秒内删除、释放或休眠该job，这个job就会超时，服务端会主动释放该job。最小ttr为1。如果客户端设置了0，服务端会默认将其增加到1。
• <bytes> 是一个整形数，表示job体的大小，不包括结尾的”\r\n”。这个 值不能大于max-job-size（默认值为2*16）。
• <data> 是job体，是一个长度为<byetes> 的字符序列。 在发送命令行和job体之后，客户端等待如下的响应：

"INSERTED <id>" 表示成功。<id> 是新job的数字编号。 
"BURIED <id>"   表示服务端没有足够的内存将job添加到优先级队列 中。<id> 是新job的数字编号。 
"EXPECTED_CRLF" 表示该job必须以CR-LF对，及 ”\r\n” 结尾。
                这两个字节在客户端的put命令中将不会被计算到job大小中。  
"JOB_TOO_BIG"   表示客户端发送一个超过max-job-size字节的job体。
"DRAINING"      表示服务端已进入”drain mode”，将不会再接收新的job。 
                客户端应该超时其他的服务端或者断开连接稍后重试。

例如：

put 1 0 30 10
abcde12345

2.2 use

use 命令是为producer设计的。put命令会将job放入由该命令指定的tube中。如果没有执行use命令，job将会被放入”default” tube。

use <tube>

tube是一个不超过200字节的名字。通过名字来指定使用哪个tube。如果该tube不存在，就会被自动创建。  唯一的响应是：  USING <tube>  <tube>是现在正在使用的tube的名称.

三、Worker命令

3.1 reserve

一个进程可以通过reserve、delete、 release和bury命令来从队列里面消耗job。

reserve命令如下：

 reserve

或者，可以指定一个超时时间：

 reserve-with-timeout <seconds>

beanstalkd将一直等待发送响应，直到一个job可用。当一个job被客户端获取，客户端必须在TTR时间内完成该job，否则job就会超时。当该job超时，服务端会将该job重新放回ready队列。TTR和当前剩余时间都可以在stats-job命令的响应中找到。  如果超时设置为0，服务端将立刻返回一个响应或者TIME_OUT。如果超时是一个大于0的值，客户端将会在获取job请求中阻塞，直到一个job可用或者超时。  对于一个已经被获取job的TTR，最后一秒是作为安全边际被服务端保留的，在此期间，客户端将无法试图去等待别的job。如果客户端在安全边际期间发送获取job命令，或者安全边际到来时还在等待获取命令的完成，服务端将返回：

• DEADLINE_SOON  这给了客户端一个在服务端自动发布该job之前，删除或者重新发布已经获取job的机会。
• TIMED_OUT  当指定了一个非负的超时时间值，并且在超时时或没有一个job可用，服务端将返回TIMED_OUT。  否则，这条命令唯一成功的响应形式是一个文本行后跟一个job体。

执行reserve命令返回：
RESERVED <id> <bytes> 
<data>

• <id> job的id，在这个beanstalkd的实例中，代表该job的唯一整数。
• <bytes> 表示job体大小的整数，不包括结尾的 ”\r\n”。
• <data> 表示消息体，一个长度为 <bytes> 的字节序列。这是对之前put 命令job体原始字节的逐字拷贝。

3.2 delete

delete命令从服务端完全删除一个job。当客户端已经成功执行完一个job时，该job一般会被使用。客户端可以删除一个已经被获取的job，可用的job，以及被休眠的job。

delete命令如下：

delete <id>

<id> 表示要删除的job id。 客户端将等待如下的响应行：

• “DELETED” 表示已经成功删除。
• “NOT_FOUND” 表示该job不存在，或者该job没有被客户端获取， 已经不在ready或buried状态。这种情况发生这客户端发送delete命令之前，该job已经超时。

3.3 release 

release命令将一个已经被获取的job重新放回ready队列（并将job状态置为 “ready”），让该job可以被其他客户端执行。这个命令经常在job因为短暂的错误而失败时使用。

格式如下：

release <id> <pri> <delay>

• <id> 表示要release的job id。
• <pri> 表示给该job分配的新的优先级。
• <delay> 表示在该job被放入ready队列之前需要等待的秒数。在此期间， job的状态将是”delayed”。

客户端期待的响应如下：

• “RELEASED” 表示成功
• “BURIED” 表示服务端没有足够的内存将job添加到优先级队列中。
• “NOT_FOUND” 表示该job不存在或没有被客户端获取。

3.4 bury

bury命令将一个job的状态置为”buried”。Buried job被放在一个FIFO的链表中，在客户端调用kick命令之前，这些job将不会被服务端处理。

bury命令格式如下：

bury <id> <pri>

• <id> 表示该job的id
• <pri> 表示分配给该job新的优先级

有两种可能的响应：

• “BURIED” 表示成功
• “NOT_FOUND” 表示该job不存在或没有被客户端获取。

3.5 touch

touch命令允许一个worker请求在一个job获取更多执行的时间。这对于那些需要长时间完成的job是非常有用的，但同时也可能利用TTR的优势将一个job从一个无法完成工作的worker处移走。一个worker可以通过该命令来告诉服务端它还在执行该job（比如：在收到DEADLINE_SOON是可以发生给命令）。

touch命令格式如下：

touch <id>

• <id> 表示当前连接获取job的id

有两种可能的响应：

• “TOUCHED” 表示成功
• “NOT_FOUND” 表示该job不存在或没有被客户端获取。

3.6 watch

watch命令将一个tube名称加入当前连接的watch list。reserve命令将从watch list里面的任意一个tube中获取job。对于每个新建的连接，watch list中只有一个”default” tube。

watch <tube>

• <tube> 是一个不超过200字节的名称。它指定将一个tube加入到watch  list。如果该tube不存在，将会被及时创建。

响应是：

• WATCHING <count> <count> 表示当前watch list中的tube数目

3.7 ignore

ignore命令是为consumer设计的。ignore命令将一个tube从当前连接的watch list中移除。

ignore <tube>

响应如下：

• “WATCHING <count>” 表示成功。<count>表示当前watch list中的 tube数目。
• “NOT_IGNORED” 表示客户端正在试图ignore watch list中的最后一 个tube。

四、其他命令

4.1 stats-job

查询job的状态

stats-job <id>

4.2 peek  

peek命令可以让客户端检查系统中的job。这个命令有4个变种。除第一个命令之外，其他3个命令都只能作用在当前使用的tube上面。

• “peek <id>” 返回编号为<id>的job。
• “peek-ready” 返回当前tube下一个ready的job。
• “peek-delayed” 返回当前tube剩余delay时间最短的job。
• “peek-buried” 返回当前tube buried list中下一个job。
  有两种可能的响应：
  1、其中一个是单行：  “NOT_FOUND” 表示请求的job不存在，或者没有job在当前请求的状态队列中。
  2、另一个是一行跟一个块数据，表示命令执行成功：  FOUND <id> <bytes> <data>
  <id> 表示job的id。
  <bytes> 表示job体大小的整数，不包括结尾的 ”\r\n”。
  <data> 表示消息体，一个长度为 <bytes> 的字节序列。

 

4.3 kick

kick命令只能针对当前正在使用的tube执行。它将buried或者delayed状态的job移动到ready队列。

命令格式如下：

kick <bound>

• <bound> 表示每次kick job的上限，服务端将最多kick <bound>个job。

响应格式如下：

• KICKED <count> <count> 表示本次kick操作作用job的数目。

4.4 list-tubes

list-tubes命令返回已经存在的所有tube的列表。

格式如下：

 list-tubes 

响应如下：

OK <bytes>
<data>

• <bytes> 是<data>的字节大小。
• <data>是一个长度为<bytes> 的字节序列。它是一个包含所有tube 名称 的YAML文件。

4.5 list-tube-used

list-tube-used命令返回客户当前正在使用的tube。

格式如下：

list-tube-used

响应如下：

USING <tube>

• <tube> 是正在使用的tube 名称。

4.6 list-tubes-watched

list-tubes-watched命令返回客户端当前正在关注的tube名称列表。

格式如下：

list-tubes-watched

响应如下：

OK <bytes>
<data>

• <bytes> 是<data>的字节大小。
• <data>是一个长度为<bytes> 的字节序列。它是一个包含被关注tube 名 称的YAML文件。

4.7 pause-tube

pause-tube命令用来在给定时间内暂停从tube获取job。

格式如下：

 pause-tube <tube-name> <delay>

• <tube> 表示要暂停的tube。
• <delay> 表示在可以从tube获取job之前需要等待的秒数。 有两种可能的响应：  “PAUSED” 表示成功。  “NOT_FOUND” 表示该tube不存在。

4.8 quit

quit命令用来关闭当前连接。

格式如下：

quit