From b1afccab1f2457f2f8635fa73db3d48e358ea3fa Mon Sep 17 00:00:00 2001 From: liuding Date: Mon, 29 Feb 2016 14:53:48 +0800 Subject: [PATCH] update doc --- README_cn.md | 8 ++++---- README_en.md | 4 ++-- doc/en/proto.md | 50 +------------------------------------------------ doc/en/push.md | 18 +++++++++++++++++- doc/proto.md | 49 +----------------------------------------------- doc/push.md | 28 ++++++++++++++++++++++----- 6 files changed, 48 insertions(+), 109 deletions(-) diff --git a/README_cn.md b/README_cn.md index b94484ba..c8a0b797 100644 --- a/README_cn.md +++ b/README_cn.md @@ -17,11 +17,11 @@ goim * 轻量级 * 高性能 * 纯Golang实现 - * 支持单个、多个以及广播消息推送 + * 支持单个、多个、单房间以及广播消息推送 * 支持单个Key多个订阅者（可限制订阅者最大人数） * 心跳支持（应用心跳和tcp、keepalive、http long pulling） * 支持安全验证（未授权用户不能订阅） - * 多协议支持（websocket，tcp，http） + * 多协议支持（websocket，tcp） * 可拓扑的架构（job、logic模块可动态无限扩展） * 基于Kafka做异步消息推送 @@ -39,8 +39,8 @@ kafka在官网已经描述的非常详细，在这里就不过多说明，安装 1.下载源码(根据自己的系统下载对应的[安装包](http://golang.org/dl/)) ```sh $ cd /data/programfiles -$ wget -c --no-check-certificate https://storage.googleapis.com/golang/go1.5.linux-amd64.tar.gz -$ tar -xvf go1.5.linux-amd64.tar.gz -C /usr/local +$ wget -c --no-check-certificate https://storage.googleapis.com/golang/go1.5.2.linux-amd64.tar.gz +$ tar -xvf go1.5.2.linux-amd64.tar.gz -C /usr/local ``` 2.配置GO环境变量 (这里我加在/etc/profile.d/golang.sh) diff --git a/README_en.md b/README_en.md index 2e47bf22..bc32abb0 100644 --- a/README_en.md +++ b/README_en.md @@ -16,11 +16,11 @@ goim * Light weight * High performance * Pure Golang - * Supports single push, multiple push and broadcasting + * Supports single push, multiple push, room push and broadcasting * Supports one key to multiple subscribers (Configurable maximum subscribers count) * Supports heartbeats (Application heartbeats, TCP, KeepAlive, HTTP long pulling) * Supports authentication (Unauthenticated user can't subscribe) - * Supports multiple protocols (WebSocket，TCP，HTTP） + * Supports multiple protocols (WebSocket，TCP） * Scalable architecture (Unlimited dynamic job and logic modules) * Asynchronous push notification based on Kafka diff --git a/doc/en/proto.md b/doc/en/proto.md index 76c2657f..ac225ad8 100644 --- a/doc/en/proto.md +++ b/doc/en/proto.md @@ -1,53 +1,5 @@ # comet and clients protocols -comet supports three protocols to communicate with client: HTTP long polling, WebSocket, TCP - -## http long polling - -**Request URL** - -http://DOMAIN/sub?param=value - -**Request Method** - -GET - -**Request Parameters** - -| parameter | is required | type | comment| -| :----- | :--- | :--- | :--- | -| ver | true | int | Protocol version | -| op | true | int | Operation | -| seq | true | int | Sequence number (Server returned number maps to client sent) | -| t | true | string | Authentication ticket. User to verify and get user's real ID | -| cb | false | string | jsonp callback | - -**Response Result** - -```json -{ - "ver": 102, - "op": 10, - "seq": 10, - "body": {"data": "xxx"} -} -``` - -**Response Fields** - -| response key | type | comment| -| :----: | :---: | :-----:| -| ver | int | Protocol version| -| op | int | Operation | -| seq | int | Sequence number| -| body | json | The JSON message pushed | - -**HTTP response code** - -| response code | comment | -| :---- | :--- | -| 200 | Success | -| 403 | Authenticate failed | -| 500 | Internal Server Error| +comet supports two protocols to communicate with client: WebSocket, TCP ## websocket **Request URL** diff --git a/doc/en/push.md b/doc/en/push.md index 55e91657..1848ab4c 100644 --- a/doc/en/push.md +++ b/doc/en/push.md @@ -6,6 +6,7 @@ push HTTP interface protocols for pusher | :---- | :---- | :---- | | [single push](#single push) | /1/push | POST | | [multiple push](#multiple push) | /1/pushs | POST | +| [room push](#room push) | /1/push/room | POST | | [broadcasting](#broadcasting) | /1/push/all | POST |

Public response body

@@ -54,11 +55,26 @@ curl -d "{\"u\":[1,2,3,4,5],\"m\":{\"test\":1}}" http://127.0.0.1:7172/1/pushs } +##### room push + * Example request + +```sh +curl -d "{\"test\": 1}" http://127.0.0.1:7172/1/push/room?rid=1 +``` + + * Response + +
+{
+    "ret": 1
+}
+
+ ##### Broadcasting * Example request ```sh -curl -d "{\"test\": 1}" http://172.16.0.239:7172/1/push/all +curl -d "{\"test\": 1}" http://127.0.0.1:7172/1/push/all ``` * Response diff --git a/doc/proto.md b/doc/proto.md index 03326790..b07565cb 100644 --- a/doc/proto.md +++ b/doc/proto.md @@ -1,52 +1,5 @@ # comet 客户端通讯协议文档 -comet支持三种协议和客户端通讯，http long polling, websocket， tcp。 -## http long polling - -**请求URL** - -http://DOMAIN/sub?param=value - -**HTTP请求方式** - -GET - -**请求参数** - -| 参数名 | 必选 | 类型 | 说明 | -| :----- | :--- | :--- | :--- | -| ver | true | int | 协议版本号 | -| op | true | int | 指令 | -| seq | true | int | 序列号（服务端返回和客户端发送一一对应） | -| t | true | string | 授权令牌，用于检验获取用户真实用户Id | -| cb | false | string | jsonp callback | - -**返回结果** - -```json -{ - "ver": 102, - "op": 10, - "seq": 10, - "body": {"data": "xxx"} -} -``` - -**字段说明** - -| 返回值字段 | 字段类型 | 字段说明 | -| :----: | :---: | :-----: | -| ver | int | 协议版本 | -| op | int | 指令 | -| seq | int | 序列号 | -| body | json | 业务方推送数据（必须是json） | - -**http状态吗说明** - -| 返回码 | 说明 | -| :---- | :--- | -| 200 | 请求成功 | -| 403 | 认证失败 | -| 500 | 内部错误 | +comet支持两种协议和客户端通讯 websocket， tcp。 ## websocket **请求URL** diff --git a/doc/push.md b/doc/push.md index 48cb7fa8..b334edec 100644 --- a/doc/push.md +++ b/doc/push.md @@ -4,8 +4,9 @@ push http接口文档，用于推送接口接入

接口汇总

| 接口名 | URL | 访问方式 | | :---- | :---- | :---- | -| [单个推送](#单个推送) | /1/push | POST | -| [批量推送](#批量推送) | /1/pushs | POST | +| [单人推送](#单个推送) | /1/push | POST | +| [单消息多人推送](#单消息多人推送) | /1/pushs | POST | +| [房间推送](#房间推送) | /1/push/room | POST | | [广播](#广播) | /1/push/all | POST |

公共返回码

@@ -23,7 +24,7 @@ push http接口文档，用于推送接口接入 -##### 单个推送 +##### 单人推送 * 请求例子 ```sh @@ -39,7 +40,7 @@ curl -d "{\"test\":1}" http://127.0.0.1:7172/1/push?uid=0 } -##### 批量推送 +##### 单消息多人推送 * 请求例子 ```sh @@ -54,11 +55,26 @@ curl -d "{\"u\":[1,2,3,4,5],\"m\":{\"test\":1}}" http://127.0.0.1:7172/1/pushs } +##### 房间推送 + * 请求例子 + +```sh +curl -d "{\"test\": 1}" http://127.0.0.1:7172/1/push/room?rid=1 +``` + + * 返回 + +
+{
+    "ret": 1
+}
+
+ ##### 广播 * 请求例子 ```sh -curl -d "{\"test\": 1}" http://172.16.0.239:7172/1/push/all +curl -d "{\"test\": 1}" http://127.0.0.1:7172/1/push/all ``` * 返回 @@ -68,3 +84,5 @@ curl -d "{\"test\": 1}" http://172.16.0.239:7172/1/push/all "ret": 1 } + +