Beanstalkd中文協議解讀

Beanstalkd中文協議解讀

這篇精彩的翻譯來自 http://www.fzb.me/2015-3-21-beanstalkd-protocol-chinese-version.html

最近有需求做全平臺的定時器，業務複雜，效能要求高，linux crontab的方式不適用，調研一些支援定時執行的記憶體佇列系統，其中beanstalkd較適合。先將其協議研究一遍，使用就不是問題了。

總括

beanstalkd協議基於ASCII編碼執行在tcp上。客戶端連線伺服器併傳送指令和資料，然後等待響應並關閉連線。對於每個連線，伺服器按照接收命令的序列依次處理並響應。所有整型值都非負的十進位制數，除非有特別宣告。

名稱約定

所有名稱必須是ASCII碼字串，即包括：

• 字母 (A-Z and a-z)
• 數字 (0-9)
• 連字元 ("-")
• 加號 ("+")
• 斜線 ("/")
• 分號 (";")
• 點 (".")
• 美元符 ("$")
• 下劃線 ("_")
• 括號 ("(" and ")")

注意：名稱不能以連字元開始，並且是以空白字元結束，每個名稱至少包含一個字元。

錯誤說明

| 返回的錯誤 | 描述 | | --------------------------------------- | -------- | | 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

• <pri> 整型值，為優先順序，可以為0-2^32（4,294,967,295），值越小優先順序越高，預設為1024。
• <delay> 整型值，延遲ready的秒數，在這段時間job為delayed狀態。
• <ttr> -- time to run --整型值，允許worker執行的最大秒數，如果worker在這段時間不能delete，release，bury job，那麼job超時，伺服器將release此job，此job的狀態遷移為ready。最小為1秒，如果客戶端指定為0將會被重置為1。
• <bytes> 整型值，job body的長度，不包含\r\n，這個值必須小於max-job-size，預設為2^16。
• <data> job body

響應 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 \r\n\r\n `` bytes 為接下來的data區塊的長度 data 為YAML file的統計資訊 其中YAML file包括的key有： -id表示job id -tube表示tube的名稱 -state表示job的當前狀態 -pri表示job的優先順序 -age表示job建立的時間單位秒 -time-left表示job的狀態遷移為ready的時間，僅在job狀態為reserved或者delayed時有意義，當job狀態為reserved時表示剩餘的超時時間。 -file表示包含此job的binlog序號，如果沒有開啟它將為0 -reserves表示job被reserved的次數 -timeouts表示job處理的超時時間 -releases表示job被released的次數 -buries表示job被buried的次數 -kicks` 表示job被kiced的次數

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有： - name 表示tube的名稱 - current-jobs-urgent 此tube中優先順序小於1024狀態為ready的job數量 - current-jobs-ready 此tube中狀態為ready的job數量 - current-jobs-reserved 此tube中狀態為reserved的job數量 - current-jobs-delayed 此tube中狀態為delayed的job數量 - current-jobs-bureid 此tube中狀態為buried的job數量 - total-jobs 此tube中建立的所有job數量 - current-using 使用此tube開啟的連線數 - current-wating 使用此tube開啟連線並且等待響應的連線數 - current-watching 開啟的連線監控此tube的數量 - pause 此tube暫停的秒數 - cmd-delete 此tube中總共執行的delete指令的次數 - cmd-pause-tube 此tube中總共執行pause-tube指令的次數 - pause-time-left 此tube暫停剩餘的秒數

stats

說明 返回整個訊息佇列系統的整體資訊 格式 stats\r\n 響應 OK <bytes>\r\n<data>\r\n bytes 為接下來的data區塊的長度 data 為YAML file的統計資訊 其中YAML file包括的key有（所有的資訊都累積的，自從beanstalkd程式啟動以來，這些資訊不儲存在binlog中）： - current-jobs-urgent 優先順序小於1024狀態為ready的job數量 - current-jobs-ready 狀態為ready的job數量 - current-jobs-reserved 狀態為reserved的job數量 - current-jobs-delayed 狀態為delayed的job數量 - current-jobs-bureid 狀態為buried的job數量 - cmd-put 總共執行put指令的次數 - cmd-peek 總共執行peek指令的次數 - cmd-peek-ready 總共執行peek-ready指令的次數 - cmd-peek-delayed 總共執行peek-delayed指令的次數 - cmd-peek-buried 總共執行peek-buried指令的次數 - cmd-reserve 總共執行reserve指令的次數 - cmd-use 總共執行use指令的次數 - cmd-watch 總共執行watch指令的次數 - cmd-ignore 總共執行ignore指令的次數 - cmd-release 總共執行release指令的次數 - cmd-bury 總共執行bury指令的次數 - cmd-kick 總共執行kick指令的次數 - cmd-stats 總共執行stats指令的次數 - cmd-stats-job 總共執行stats-job指令的次數 - cmd-stats-tube 總共執行stats-tube指令的次數 - cmd-list-tubes 總共執行list-tubes指令的次數 - cmd-list-tube-used 總共執行list-tube-used指令的次數 - cmd-list-butes-watched 總共執行list-tubes-watched指令的次數 - cmd-pause-tube 總共執行pause-tube指令的次數 - job-timeouts 所有超時的job的總共數量 - total-jobs 建立的所有job數量 - max-job-size job的資料部分最大長度 - current-tubes 當前存在的tube數量 - current-connections 當前開啟的連線數 - current-producers 當前所有的開啟的連線中至少執行一次put指令的連線數量 - current-workers 當前所有的開啟的連線中至少執行一次reserve指令的連線數量 - current-waiting 當前所有的開啟的連線中執行reserve指令但是未響應的連線數量 - total-connections 總共處理的連線數 - pid 伺服器程式的id - version 伺服器版本號 - rusage-utime 程式總共佔用的使用者CPU時間 - rusage-stime 程式總共佔用的系統CPU時間 - uptime 伺服器程式執行的秒數 - binlog-oldest-index 開始儲存jobs的binlog索引號 - binlog-current-index 當前儲存jobs的binlog索引號 - binlog-max-size binlog的最大容量 - binlog-records-written binlog累積寫入的記錄數 - binlog-records-migrated is the cumulative number of records written as part of compaction. - id 一個隨機字串，在beanstalkd程式啟動時產生 - hostname 主機名

list-tubes

說明 列表所有存在的tube 格式 list-tubes\r\n

響應 ``` OK \r\n

\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 \r\n

\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

參考地址 ：協議中文解讀from fzb.me