DOC: add throttler api docs

README.md

@@ -52,8 +52,10 @@ To start in developing mode:
 ## DOCs
 
 * [HTTP API Doc](https://github.com/bitleak/lmstfy/blob/master/doc/API.md)
+* [Throtter API Doc](https://github.com/bitleak/lmstfy/blob/master/doc/throtter.en.md)
 * [Administration API Doc](https://github.com/bitleak/lmstfy/blob/master/doc/administration.en.md)
 * [管理 API 中文文档](https://github.com/bitleak/lmstfy/blob/master/doc/administration.cn.md)
+* [限流 API 中文文档](https://github.com/bitleak/lmstfy/blob/master/doc/throtter.cn.md)
 
 ---
 

doc/throttler.cn.md

@@ -0,0 +1,67 @@
+## Throttler API
+
+限流目前是针对 token 级别来限制消费/写入 QPS 而不是消息数，如果希望限制消息数，那么就不要使用批量消费 API 即可，当消费/写入达到限制频率时接口会返回 `429` 的状态码。
+
+> 注意:为了性能考虑，限制阀值目前是异步每 10s 更新一次，增加或者删除不会需要等待异步更新才会生效
+
+### 创建限速器 
+
+```
+POST /token/:namespace/:token/limit
+```
+
+#### Request Body 
+
+```
+{
+"read": 100,
+"write": 200,
+"interval": 10
+}
+```
+
+`interval` 的单位是 秒，`read/write` 的单位是次数，上面的意思是这个 token 在 10s 之内最多可以消费 100 次以及写入 200 次。
+
+### 查看限制器 
+
+```
+GET /token/:namespace/:token/limit
+```
+
+#### Request Query
+
+no parameter
+
+### 设置限制器
+
+```
+PUT /token/:namespace/:token/limit
+```
+#### Request Body 
+
+```
+{
+"read": 200,
+"write": 400,
+"interval": 10
+}
+```
+
+### 删除限制器 
+
+```
+DELETE /token/:namespace/:token/limit
+```
+
+#### Request Query
+
+no parameter
+
+### 罗列限制器
+```
+GET /limits
+```
+
+#### Request Query
+
+no parameter

doc/throttler.en.md

@@ -0,0 +1,68 @@
+## Throttler API
+The throttler only limits the rate of token consume/publish QPS instead of messages, don't use batch consume if you want to limit the rate of message.
+Consume/Produce API would return the status code `429`(too many requests) when the token has reached the rate limit.
+
+> CAUTION: consideration of the performance, we sync limiters every 10 seconds instead of fetching the limit every time. 
+
+### Create the limit
+
+```
+POST /token/:namespace/:token/limit
+```
+#### Request Body 
+
+```
+{
+"read": 100,
+"write": 200,
+"interval": 10
+}
+```
+
+The unit of the `interval` is second and `read`/`write` is counter, which means this token can consume 100 times
+and publish 200 times at 10 seconds.
+
+### Get the limit
+
+```
+GET /token/:namespace/:token/limit
+```
+
+#### Request Query
+
+no parameter
+
+### Set the limit
+
+```
+PUT /token/:namespace/:token/limit
+```
+#### Request Body 
+
+```
+{
+"read": 200,
+"write": 400,
+"interval": 10
+}
+```
+
+### Delete the limit
+
+```
+DELETE /token/:namespace/:token/limit
+```
+
+#### Request Query
+
+no parameter
+
+### List the limit
+
+```
+GET /limits
+```
+
+#### Request Query
+
+no parameter