Initialize

doc/protocol.zh-CN.md

@@ -0,0 +1,623 @@
+# 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](http://groups.google.com/group/beanstalk-talk).|
+| `BAD_FORMAT\r\n`                         | 格式不正确，客户端发送的指令格式出错，有可能不是以 `\r\n` 结尾，或者要求整型值等等 |
+| `UNKNOWN_COMMAND\r\n`                   | 未知的命令，客户端发送的指令服务器不理解 |
+
+### job 的生命周期
+
+Client 使用 put 命令创建一个工作任务 job. 在整个生命周期中 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 典型的生命周期
+
+```text
+   put            reserve               delete
+  -----> [READY] ---------> [RESERVED] --------> *poof*
+```
+
+#### job 可能的状态迁移
+
+```text
+   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，用来储存统一类型的 job.每个 tube 由一个就绪 (`ready`) 队列与延迟 (`delayed`) 队列组成.每个 job 所有的状态迁移在一个 tube 中完成.通过发送 `watch` 指令, 消费者 consumers 可以监控感兴趣的 tube.通过发送 `ignore` 指令, 消费者 consumers 可以取消监控 tube.通过 `list-tubes-watched`命令返回所有监控的 tubes，当客户端预订 (`reserved`) 一个 job，此 job 可能来自任何一个它监控的 tube.
+
+当一个客户端连接上服务器时，客户端监控的 tube 默认为 `defaut`，如果客户端提交 job 时，没有使用 `use` 命令，那么这些 job 就存于名为`default`的 tube 中.
+
+tube 按需求创建，无论他们在什么时候被引用到.如果一个 tube 变为空（即 no ready jobs，no delayed jobs，no buried jobs）和没有任何客户端引用(being watched)，它将会被**自动删除**.
+
+### 指令说明（Commands）
+
+#### 生产者指令说明（Producer Commands）
+
+#### `put`
+
+插入一个 job 到队列
+
+**指令格式**
+
+```text
+put <pri> <delay> <ttr> <bytes>\r\n
+<data>\r\n
+```
+
+* `<pri>` 整型值, 为优先级, 可以为0-2^32 (4,294,967,295) 值越小优先级越高, 默认为1024.
+* `<delay>` 整型值，延迟`ready`的秒数，在这段时间 job 为 `delayed` 状态. 最大 delay 值为 2^32-1.
+* `<ttr>` -- time to run --整型值，允许 worker 执行的最大秒数，如果 worker 在这段时间不能 delete，release，bury job，那么当 job 超时，服务器将**自动** release 此job，此 job 的状态迁移为`ready`. 最小为 1 秒，如果客户端指定为 0 将会被重置为 1. 最大 ttr 值为 2^32-1.
+* `<bytes>` 整型值，job body的长度，不包含`\r\n`，这个值必须小于 `max-job-size`，默认为 2^16.
+* `<data>`   job body
+
+**响应**
+
+```text
+INSERTED <id>\r\n
+```
+
+表示插入 job 成功，id 为新 job 的任务标识，整型值 (uint64)
+
+```text
+BURIED <id>\r\n
+```
+
+如服务器为了增加队列的优先级而，内存不足时返回，id 为新 job 的任务标识，整型值 (uint64)
+
+```text
+EXPECTED_CRLF\r\n
+```
+
+job body 必须以 `\r\n` 结尾
+
+```text
+JOB_TOO_BIG\r\n
+```
+
+job body 的长度超过 `max-job-size`
+
+```text
+DRAINING\r\n
+```
+
+表示服务器资源耗尽，表示服务器已经进入了`drain mode`，服务器再也不能接受连接，客户端应该使用其他服务器或者断开稍后重试
+
+#### `use`
+
+producer 生产者使用，之后使用的 put 指令，都将会把 job 放置于 use 的 tube 中，如果没有指定 use 的 tube， 任务 job 将会进入默认名称为 `default` 的 tube 
+
+**指令格式**
+
+```text
+use <tube>\r\n
+tube tube 的名称，最大为 200 字节，不存在时将自动创建
+```
+
+**响应**
+
+```text
+USING <tube>\r\n tube 为正在使用的tube名称
+```
+
+#### 消费者指令说明（Worker Commands）
+
+#### `reserve`
+
+预订(reserved) job 等待处理. beanstalkd 将返回一个新预订的 job，如果没有 job，beanstalkd 将一直等待到有 job 时才发送响应. 一旦 job 状态迁移为 `reserved`, 取出 job 的 client 被限制在指定的时间（如果设置了ttr）完成，否则将超时，job 状态重装迁移为ready.
+
+**指令格式**
+
+```text
+reserve\r\n
+```
+
+可选的一个相似的命令
+`reserve-with-timeout \r\n` 设置取 job 的超时时间，timeout 设置为 0 时，服务器立即响应或者 TIMED_OUT，积极的设置超时，将会限制客户端阻塞在取 job 的请求的时间.
+
+##### 失败响应
+
+```text
+DEADLINE_SOON\r\n
+```
+
+* 在一个预定的任务 job 的运行时间内, **最后一秒**会被服务器保持为一个**安全边际**，在这个**时间间隔** (1s) 中，client 将无法获取其他任务. 如果客户端在安全隔离期间发出一个预留 (reserve) 指令，或者客户端在等候一个预定 (reserve) 指令返回结果时，client 安全隔离期到达时，将会收到 `DEADLINE_SOON` 回复
+* `DEADLINE_SOON` 的返回结果提示 client 这是一个 delete 或者 touch 它所预订(reserved) 的任务 job 的时机，之后 beanstalkd 服务端将会自动释放 `ttr` 到期的 job
+
+```text
+TIMED_OUT\r\n 超时
+```
+
+##### 成功响应
+
+```text
+RESERVED <id> <bytes>\r\n
+<data>\r\n
+```
+
+成功取出 job:
+
+* `<id>` 为 job id,整型值
+* `<bytes>` 为 job body 的长度，不包含`\r\n`，
+* `<data>` 为job body
+
+#### `delete`
+
+从队列中删除一个job
+
+**指令格式**
+
+```text
+delete <id>\r\n
+```
+
+* `<id>` 为 job id
+
+**响应**
+
+```text
+DELETED\r\n
+```
+
+* 删除成功
+
+```text
+NOT_FOUND\r\n
+```
+
+* job 不存在时，或者 job 并不为当前的 client 所 reserved;
+* job 的状态不为 `ready`和 `buried`（这种情况是在 job 被其他 client 所预订(reserved) 且还未执行超时，此时当前 client 发送了 delete 指令就会收到 `NOT_FOUND` 回复）
+
+#### `release`
+
+release 指令将一个`reserved`的 job 恢复为`ready`. 它通常在 job 执行失败时使用.
+
+**指令格式**
+
+```text
+release <id> <pri> <delay>\r\n
+```
+
+* `<id>` 为job id
+* `<pri>` 为 job 的优先级
+* `<delay>` 为延迟`ready`的秒数
+
+
+**响应**
+
+```text
+RELEASED\r\n 表明成功
+BURIED\r\n 如服务器为了增加队列的优先级而，内存不足时返回
+bury <id> <pri>\r\n
+```
+
+* `<id>` 为 job id
+* `<pri>` 为优先级
+
+**响应**
+
+```text
+BURIED\r\n 表明成功
+NOT_FOUND\r\n 如果 job 不存在或者 client 没有预订此 job
+```
+
+#### `touch`
+
+允许 worker 请求更多的时间执行 job；当 job 需要更长的时间来执行，这个指令就将会起作用，worker 可用周期性的告诉服务器它仍然在执行job（可以被 `DEADLINE_SOON` 触发）
+
+**指令格式**
+
+```text
+touch <id>\r\n
+```
+
+* `<id>` 为 job id
+
+**响应**
+
+```text
+TOUCHED\r\n 表明成功
+NOT_FOUND\r\n 如果 job 不存在或者 client 没有预订此 job
+```
+
+#### `watch`
+
+添加监控的 tube 到 watch list 列表，reserve 指令将会从监控的 tube 列表获取 job，对于每个连接，监控的列表默认为 `default`
+
+**指令格式**
+
+```text
+watch <tube>\r\n
+```
+
+* `<tube>` 为监控的 tube 名称，名称最大为 200 字节，如果 tube 不存在会**自动创建**
+
+**响应**
+
+```text
+WATCHING <count>\r\n 表明成功
+```
+
+* `<count>` 整型值，已监控的 tube 数量
+
+#### `ignore`
+
+从已监控的 watch list 列表中移出特定的 tube 
+
+**指令格式**
+
+```text
+ignore <tube>\r\n
+```
+
+* `<tube>` 为移出的 tube 名称，名称最多为 200 字节，如果 tube 不存在会自动创建
+
+**响应**
+
+```text
+WATCHING <count>\r\n 表明成功
+```
+
+* `<count>` 整型值，已监控的tube数量
+
+```text
+NOT_IGNORED\r\n
+```
+
+* 如果 client 尝试忽略其仅有的tube时的响应
+
+#### 其他指令说明（Other Command）
+
+#### `peek`
+
+让 client 在系统中检查 job，有四种形式的命令，其中第一种形式的指令是针对当前使用 (use) 的 tube
+
+**指令格式**
+
+```text
+peek <id>\r\n  返回 id 对应的 job
+peek-ready\r\n 返回下一个 ready job
+peek-delayed\r\n 返回下一个延迟剩余时间最短的 job
+peek-buried\r\n 返回下一个在 buried 列表中的 job
+```
+
+**响应**
+
+```text
+NOT_FOUND\r\n
+``` 
+
+* 如果 job 不存在，或者没有对应状态的 job
+
+```text
+FOUND <id> <bytes>\r\n <data>\r\n
+```
+
+* `<id>` 为对应的 job id
+* `<bytes>` job body 的字节数
+* `<data>` 为 job body
+
+#### `kick`
+
+此指令应用在当前使用 (use) 的 tube 中，它将 job 的状态迁移为`ready`或者`delayed`
+**指令格式**
+
+```text
+kick <bound>\r\n
+```
+
+* `<bound>` 整型值，唤醒的 job 上限
+
+**响应**
+
+```
+KICKED <count>\r\n
+```
+* `<count>` 为真实唤醒的job数量
+
+#### kick-job
+
+kick 指令的一个变体，可以使单个 job 被唤醒，使一个状态为`buried`或者`delayed`的 job迁移为`ready`，所有的状态迁移都在相同的 tube 中完成
+
+**指令格式**
+
+```text
+kick-job <id>\r\n
+```
+* `<id>` 为job id
+
+**响应**
+`NOT_FOUND\r\n` 如果 job 不存在，或者 job 是不可唤醒的状态
+`KICKED\r\n` 表明成功
+
+#### `stats-job`
+
+统计 job 的相关信息
+
+**指令格式**
+
+```text
+stats-job <id>\r\n
+```
+
+* `<id>` 为 job id
+
+**响应**
+
+```text
+NOT_FOUND\r\n 如果job不存在
+
+OK <bytes>\r\n<data>\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 的相关信息
+
+**指令格式**
+
+```text
+stats-tube <tube>\r\n
+```
+
+* `<tube>` 为对应的 tube 的名称，最多为 200 字节
+
+**响应**
+
+```text
+NOT_FOUND\r\n
+```
+* 如果tube不存在
+
+```text
+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`
+
+返回整个消息队列系统的整体信息
+
+**指令格式**
+
+```text
+stats\r\n
+```
+
+**响应**
+
+```text
+OK <bytes>\r\n
+<data>\r\n
+```
+* `<bytes>` 为接下来的 data 区块的长度
+* `<data>` 为 YAML file 的统计信息
+
+从 beanstalkd 进程启动以来，所有的信息都累积的，这些信息不储存在 binlog 中
+其中 YAML file 包括的key有：
+
+* `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-tubes-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`
+
+列出当前 beanstalkd 所有存在的 tubes
+
+**指令格式**
+
+```text
+list-tubes\r\n
+```
+
+**响应**
+
+```text
+OK <bytes>\r\n
+<data>\r\n
+```
+
+* `<bytes>` 为接下来的 data 区块的长度
+* `<data>` 为 YAML file，包含所有的 tube 名称
+
+#### `list-tube-used`
+
+列出当前 client 正在 use 的 tube
+
+**指令格式**
+
+```text
+list-tube-used\r\n
+```
+
+**响应**
+
+```text
+USING <tube>\r\n
+```
+
+* `<tube>` 为 tube 名称
+
+#### `list-tubes-watched`
+
+列出当前 client 所 watch 的 tubes
+
+**指令格式**
+
+```text
+list-tubes-watched\r\n
+```
+
+**响应**
+
+```text
+OK <bytes>\r\n
+<data>\r\n
+```
+
+* `<bytes>` 为接下来的 data 区块的长度
+* `<data>` 为 YAML file，包含所有的 tube 名称
+
+#### `quit`
+
+client 向 beanstalkd 发送 `quit` 报文，并关闭连接，beanstalkd 收到该报文后主动关闭连接
+
+**指令格式**
+
+```text
+quit\r\n
+```
+
+无响应
+
+#### `pause-tube`
+
+此指令针对特定的 tube 内所有新的 job 延迟指定的秒数
+
+**指令格式**
+
+```text
+pause-tube <tube-name> <delay>\r\n
+```
+
+* `<delay>` 延迟的时间
+
+**响应**
+
+```text
+PAUSED\r\n 表示成功
+NOT_FOUND\r\n tube 不存在
+```
+
+
+> Translated by PHPBoy :http://www.phpboy.net/ and fzb.me
+Revised by Pseudocodes: https://github.com/pseudocodes