# notice

**Repository Path**: lianzt/notice

## Basic Information

- **Project Name**: notice
- **Description**: 简单易用的 websock 服务端推送系统。
- **Primary Language**: NodeJS
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2018-06-11
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 消息推送服务

## 简介

一个简单易用的 websock 服务端推送系统，可以做为一个独立的通讯系统为其它个项目提供为用户推送消息的服务。

系统使用 ***系统名*** 与 ***用户ID*** 唯一区分一个用户，用户连接websocket后，其它系统调用开放的API，向某一用户推送消息。

客户端与服务端之间使用 websocket 长链接，客户端可以是PC浏览器，也可以是手机端浏览器，目前互联网上的业务主要集中在微信与支付宝上，自带的浏览器都是可以支持websocket的。

消息推送服务主要用于服务端主动通知客户端使用，不接收客户端主动发送的消息，推送的消息以通知为主，不发送长文本数据。

## 建立 websocket 链接

> 链接地址：http://ip:port/notice?id={id}&project={project}&sign={sign}

* id：客户端id，在一个系统中唯一代表一个客户端，可使用 sessionID，在浏览器中即为cookies.jsessionid
* project：系统名，用于标示客户端使用的系统, project + id 唯一确定一个客户端
* sign：签名验证，生成格式为md5(id + '^' + project + '^' + KEY)，推荐在服务端生成
* KEY：默认为 514En\*mJ0hVeL&e0M!fFQ3o&xhAch#zC

一个消息推送服务，最大可支持 16000+ 的客户端数量同时在线，超过这一数值客户端将无法连接服务，目前还没有集群部署方案。

#### websocket 关闭状态码

当客户端的websocket链接断开时，会通知一个 event ，该事件中包含一个状态码，有可能是服务端主动关闭，也有可能是网络异常等原因，可从状态码中判断，获取状态码的代码如下：

```
ws.onclose = function(e){
    log('server close code: ' + e.code + ', reason:' + e.reason);
}
```

状态码为1000 ~ 4999 的数字，有以下取值范围：

* 1000：服务端主动关闭
* 1001~1999：websocket api使用
* 2000~3999：为以后功能扩展预留
* 4000~4999：开发者可自定义

在接收到关闭事件时，可根据状态码判断是否要发起重连，通常服务码 1001~3999 可发起重连。重连请求应随时间推移间隔逐渐延长，可采用 2^n 递增，并设定的最大值。禁止无间隔重连。

> 可引入 ./lib/notice.js 库接入消息通知服务，按需引入 md5.js ，如果客户端基于webpack构建，可在客户端引入md5.js生成签名，其它情况最好在服务端生成签名。

## 推送消息接口

地址：/push

类型：post

参数：id=&project=&message=

向客户端推送通知，消息的格式由各系统自由定义，只可传输文本消息。

## 链接统计接口

地址：/status

类型：get

响应：返回当前各系统的连接数，\_vaild为有效链接总数，\_count为总链接数。

## notice.js 库

可在浏览器中直接引入，使用方法如下，也可参考 test/test.html 文件

```
var notice = new Notice(url);
notice.onmessage = function(message){
  console.log(message);
};
//notice.destory();   //销毁
```

依照上述代码，创建 notice 对象后，宣言 onmessage 回调即可接收消息。

当链接被关闭时，状态码为 1001~3999 的代码会触发重连机制。

定义 onclose 事件，会取消重连机制，如需手动重连，可调用 init() 方法。

## 运行

***config.js***文件为项目的配置文件，主要配置如下：
```
{
   key: '514En*mJ0hVeL&e0M!fFQ3o&xhAch#zC',       //签名key
   check_sign: true,            //是否检验签名
   project: ['alipay'],         //其它系统接入时约定的项目名
}
```

运行：

```
npm install

node app.js
```