@arcblock/ws 1.6.10

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2018-2019 ArcBlock
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,85 @@
+# Blocklet Server WebSocket
+
+> Blocklet Server PubSub base on Websocket and Phoenix Protocol
+
+## Usage
+
+1. WsServer
+
+```javascript
+const { WsServer } = require('@arcblock/ws');
+
+/**
+ * @params {Object} opts
+ *  @params {http.Server} opts.httpServer
+ *  @params {String} opts.pathname default to '/websocket'
+ *  @params {Function} opts.authenticate
+ */
+const wsServer = new WsServer({
+  httpServer: http.createServer(),
+  authenticate: (req, cb) => {
+    const { searchParams } = new URL(req.url, `http://${req.headers.host || 'unknown'}`);
+    const token = searchParams.get('token');
+    if (!token) {
+      cb(new Error('token not found'), null);
+      return;
+    }
+
+    // custom logic for validate token
+    const authInfo = validateToken(token);
+
+    // if validate success
+    cb(null, authInfo);
+
+    // if validate error
+    cb(new Error('validate fail'), null);
+  },
+});
+
+// attach to httpServer(httpServer has passed by constructor)
+wsSerer.attach();
+
+// push message
+wsServer.push('blocklet.installed', data);
+wsServer.push('notification.create', data);
+```
+
+2. WsClient
+
+WsClient is inherited from [Phoenix](https://www.npmjs.com/package/phoenix)([source](https://github.com/phoenixframework/phoenix/blob/master/assets/js/phoenix.js)),
+
+```javascript
+import WsClient from '@arcblock/ws/lib/client';
+
+// create instance
+const socket = new WsClient(`//${window.location.hostname}`, {
+  // params will be passed to server through url
+  params: () => ({
+    // token is used for authentication
+    token: window.localStorage.getItem('abt_node_login_token'),
+  }),
+
+  // Defaults to none
+  logger: (type, msg, data) => console.log(type, msg, data),
+});
+
+// connect
+socket.connect();
+
+// add subscriber
+socket.on('blocklet.installed', callback1);
+socket.on('notification.create', callback2);
+
+// remove subscriber
+socket.off('blocklet.installed', callback1);
+socket.off('notification.create', callback2);
+
+// disconnect
+socket.disconnect(() => {
+  // after disconnected...
+});
+```
+
+3. Hooks
+
+It's very simple to create hooks in react apps.

package/lib/browser.js

@@ -0,0 +1,5 @@
+const WsClient = require('./client/browser');
+
+module.exports = {
+  WsClient,
+};

package/lib/client/base.js

@@ -0,0 +1,108 @@
+const createLogger = require('../logger');
+
+module.exports = (Socket, EventEmitter, transport) => {
+  return class WsClient extends Socket {
+    constructor(endpoint, opts = {}) {
+      super(endpoint, { transport, ...opts });
+
+      this._logger = createLogger('client', opts.silent);
+      this.emitter = new EventEmitter();
+
+      this.onOpen(() => {
+        this._logger.debug('socket open', endpoint);
+      });
+      this.onClose(() => {
+        this._logger.debug('socket close', endpoint);
+      });
+      this.onError((err) => {
+        this._logger.error('socket error', err.error);
+      });
+      this.onMessage((message) => {
+        this._logger.debug('socket message', { message });
+      });
+    }
+
+    on(event, handler) {
+      this.ensureJoinChannel(event);
+      this.emitter.on(event, handler);
+    }
+
+    off(event, handler) {
+      if (handler) {
+        this.emitter.off(event, handler);
+      } else {
+        this.emitter.removeAllListeners(event);
+      }
+
+      this.ensureLeaveChannel(event);
+    }
+
+    disconnect(callback, code, reason) {
+      this.emitter.eventNames().forEach((event) => {
+        this.emitter.removeAllListeners(event);
+      });
+      super.disconnect(callback, code, reason);
+    }
+
+    /**
+     * private
+     */
+    ensureJoinChannel(event) {
+      const count = this.emitter.listenerCount(event);
+      if (count > 0) {
+        return;
+      }
+
+      const topic = event;
+      const channel = this.channel(topic);
+      channel
+        .join()
+        .receive('ok', (message) => {
+          this._logger.debug('join success', { event, message });
+        })
+        .receive('error', (error) => {
+          this._logger.error('join error', { event, error });
+        })
+        .receive('timeout', () => {
+          this._logger.debug('join timeout', { event });
+        });
+      channel.on(event, ({ status, response: data }) => {
+        if (status === 'ok') {
+          this.emitter.emit(event, data);
+        } else {
+          this._logger.debug('response error', { event, status, data });
+        }
+      });
+    }
+
+    /**
+     * private
+     */
+    ensureLeaveChannel(event) {
+      const count = this.emitter.listenerCount(event);
+      if (count > 0) {
+        return;
+      }
+
+      const topic = event;
+      const channel = this.channels.find((c) => c.topic === topic);
+      if (!channel) {
+        return;
+      }
+
+      this.remove(channel);
+      channel
+        .leave()
+        .receive('ok', (message) => {
+          this._logger.debug('leave success', { event, message });
+        })
+        .receive('error', (err) => {
+          this._logger.error('leave error', { event, err });
+        })
+        .receive('timeout', () => {
+          this._logger.debug('leave timeout', { event });
+        });
+      channel.off(event);
+    }
+  };
+};

package/lib/client/browser.js

@@ -0,0 +1,6 @@
+const EventEmitter = require('eventemitter3');
+const { Socket } = require('phoenix');
+
+const createClient = require('./base');
+
+module.exports = createClient(Socket, EventEmitter);

package/lib/client/index.js

@@ -0,0 +1,7 @@
+const EventEmitter = require('events');
+const { Socket } = require('phoenix');
+const WebSocket = require('ws');
+
+const createClient = require('./base');
+
+module.exports = createClient(Socket, EventEmitter, WebSocket);

package/lib/index.js

@@ -0,0 +1,7 @@
+const WsServer = require('./server');
+const WsClient = require('./client');
+
+module.exports = {
+  WsServer,
+  WsClient,
+};

package/lib/logger.js

@@ -0,0 +1,12 @@
+const debug = require('debug');
+
+module.exports = (subModule, silent = false) => {
+  const d = debug(['@arcblock/ws', subModule].join(':'));
+  return {
+    debug: d,
+    warn: d,
+    info: d,
+    trace: silent ? d : console.error,
+    error: silent ? d : console.error,
+  };
+};

package/lib/server/index.js

@@ -0,0 +1,381 @@
+const EventEmitter = require('events');
+const cluster = require('cluster');
+
+const uuid = require('uuid');
+const WebSocket = require('ws');
+const eventHub = cluster.isMaster ? require('@arcblock/event-hub/single') : require('@arcblock/event-hub');
+
+const createLogger = require('../logger');
+
+const sleep = (timeout) => new Promise((resolve) => setTimeout(resolve, timeout));
+
+const reply = (socket, topic, event, response, status = 'ok') => {
+  if (socket.readyState === WebSocket.OPEN) {
+    const res = JSON.stringify([socket.joinRef, socket.ref, topic, event, { status, response }]);
+    socket.send(res);
+  }
+};
+
+const noop = () => {};
+const defaultHooks = {
+  preJoinChannel: noop,
+  postJoinChannel: noop,
+  preLeaveChannel: noop,
+  postLeaveChannel: noop,
+  postBroadcast: noop,
+  postSend: noop,
+  receiveMessage: noop,
+};
+
+const refreshHeartbeat = (socket) => {
+  socket.heartbeatAt = Date.now();
+};
+
+const HEARTBEAT_TIMEOUT = 60 * 1000;
+
+/**
+ * Create a websocket server
+ *
+ * @param {Object} opts
+ * @param {String} opts.pathname - which path to mount the socket server
+ * @param {Object} opts.authenticate - authentication function to be called on connection
+ * @param {Object} opts.hooks - hooks to be called on events
+ * @param {Object} opts.logger - logger used to log messages
+ * @param {Object} opts.broadcastEventName - used in cluster mode, default is '@arcblock/ws:broadcast'
+ * @param {Object} opts.heartbeatTimeout - maximum non-response time of a connection socket
+ * @class WsServer
+ * @extends {EventEmitter}
+ */
+class WsServer extends EventEmitter {
+  constructor(opts = {}) {
+    super();
+    this.pathname = opts.pathname;
+    this.authenticate = opts.authenticate || null;
+    this.hooks = Object.assign({}, defaultHooks, opts.hooks || {});
+    this.logger = opts.logger || createLogger('server', opts.silent);
+    this.heartbeatTimeout = opts.heartbeatTimeout || HEARTBEAT_TIMEOUT;
+
+    this.wss = new WebSocket.Server({ noServer: true, clientTracking: false });
+    this.wss.on('connection', this.onWssConnection.bind(this));
+    this.wss.on('close', this.onWssClose.bind(this));
+    this.wss.on('error', this.onWssError.bind(this));
+
+    this.topics = {}; // <topic>: Set<socket>
+
+    this.broadcastEventName = opts.broadcastEventName || '@arcblock/ws:broadcast';
+    eventHub.on(this.broadcastEventName, (data) => this._doBroadCast(data));
+  }
+
+  attach(server) {
+    server.on('upgrade', this.onConnect.bind(this));
+  }
+
+  onConnect(request, socket, head) {
+    const { pathname } = new URL(request.url, `http://${request.headers.host || 'unknown'}`);
+    this.logger.debug('connect attempt', { pathname });
+    if (this.pathname && pathname !== this.pathname) {
+      socket.destroy();
+      return;
+    }
+
+    if (!this.authenticate) {
+      this.wss.handleUpgrade(request, socket, head, (ws) => {
+        this.wss.emit('connection', ws);
+      });
+      return;
+    }
+
+    this.authenticate(request, (err, authInfo) => {
+      if (err) {
+        socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+        socket.destroy();
+        return;
+      }
+      this.wss.handleUpgrade(request, socket, head, (ws) => {
+        ws.authInfo = authInfo;
+        this.wss.emit('connection', ws);
+      });
+    });
+  }
+
+  /**
+   * Broadcast message to all subscribers of a topic, can be used as
+   * - broadcast(event, data)
+   * - broadcast(topic, event, data)
+   * - broadcast(topic, event, data, options)
+   */
+  async broadcast(...args) {
+    let topic;
+    let event;
+    let data;
+    let options = {};
+    let cb = () => {};
+
+    if (typeof args[args.length - 1] === 'function') {
+      cb = args.pop();
+    }
+
+    if (args.length < 2) {
+      throw new Error('Broadcasting requires at least 2 arguments');
+    }
+    if (args.length === 2) {
+      [event, data] = args;
+      topic = event;
+    } else if (args.length === 3) {
+      [topic, event, data] = args;
+    } else {
+      [topic, event, data, options] = args;
+    }
+
+    const enableLog = options.enableLog !== undefined ? !!options.enableLog : true;
+    const replyId = uuid.v4();
+
+    // Count of clients what will receive the message
+    // The count is NOT reliable
+    let count = 0;
+    eventHub.on(replyId, ({ count: c } = {}) => {
+      if (c) {
+        count += c;
+      }
+    });
+
+    eventHub.broadcast(this.broadcastEventName, { topic, event, data, options, enableLog, replyId });
+
+    // wait 600ms for message sending by each process
+    await sleep(600);
+    eventHub.off(replyId);
+
+    const opts = { count, topic, event, data, options };
+    cb(opts);
+    try {
+      await this.hooks.postBroadcast(opts);
+    } catch (error) {
+      this.logger.error('postBroadcast error', { error });
+    }
+  }
+
+  async _doBroadCast({ topic, event, data, enableLog, replyId } = {}) {
+    try {
+      let count = 0;
+
+      if (this.topics[topic] && this.topics[topic].size) {
+        this.topics[topic].forEach((socket) => {
+          const noHeartbeatTime = Date.now() - socket.heartbeatAt;
+          if (noHeartbeatTime > this.heartbeatTimeout) {
+            this.logger.error(`Socket has no heartbeat within ${Math.floor(noHeartbeatTime / 1000)} seconds`, {
+              topic,
+              id: socket.id,
+            });
+            this.topics[topic].delete(socket);
+            return;
+          }
+
+          count++;
+          if (enableLog) {
+            this.logger.info('broadcast message to', { topic, event, id: socket.id });
+          }
+          reply(socket, topic, event, data);
+        });
+      }
+
+      if (count === 0 && enableLog) {
+        this.logger.info('no connections when broadcast message', { topic, event });
+      }
+
+      if (count > 0 && replyId) {
+        eventHub.broadcast(replyId, { count });
+      }
+    } catch (error) {
+      this.logger.error('_doBroadcast error', { error });
+    }
+  }
+
+  /**
+   * Send message to 1 subscriber of a topic, can be used as
+   * - send(socket, event, data)
+   * - send(socket, topic, event, data)
+   * - send(socket, topic, event, data, options)
+   */
+  async send(...args) {
+    let socket;
+    let topic;
+    let event;
+    let data;
+    let options = {};
+
+    if (args.length < 3) {
+      throw new Error('send requires at least 3 arguments');
+    }
+    if (args.length === 3) {
+      [socket, event, data] = args;
+      topic = event;
+    } else if (args.length === 4) {
+      [socket, topic, event, data] = args;
+    } else {
+      [socket, topic, event, data, options] = args;
+    }
+
+    const opts = { enableLog: true, ...options };
+    if (!socket) {
+      this.logger.error('socket does not exist');
+      return;
+    }
+
+    if (opts.enableLog) {
+      this.logger.info('send message to', { topic, event, id: socket.id });
+    }
+
+    reply(socket, topic, event, data);
+
+    try {
+      await this.hooks.postSend({ topic, event, data, options });
+    } catch (error) {
+      this.logger.error('postSend error', { error });
+    }
+  }
+
+  /**
+   * private
+   * @param {socket} socket
+   */
+  async onWssConnection(socket) {
+    socket.id = uuid.v4();
+    refreshHeartbeat(socket);
+    this.logger.debug('socket connected', { id: socket.id });
+
+    socket.on('message', async (msg) => {
+      this.logger.debug('socket onmessage', { msg });
+      let joinRef;
+      let ref;
+      let topic;
+      let event;
+      let payload;
+      try {
+        [joinRef, ref, topic, event, payload] = JSON.parse(msg);
+      } catch (err) {
+        this.logger.error('parse socket message error', { id: socket.id, error: err });
+        return;
+      }
+
+      if (!topic || !event) {
+        this.logger.warn('Invalid message format, topic/event fields are required');
+        return;
+      }
+
+      socket.joinRef = joinRef;
+      socket.ref = ref;
+
+      if (topic === 'phoenix' && event === 'heartbeat') {
+        // heartbeat
+        reply(socket, topic, event);
+        refreshHeartbeat(socket);
+        return;
+      }
+
+      if (event === 'phx_join') {
+        // pre hook
+        try {
+          await this.hooks.preJoinChannel({ joinRef, ref, topic, event, payload });
+        } catch (error) {
+          this.logger.error('preJoinChannel error', { error });
+          reply(socket, topic, `chan_reply_${ref}`, { message: error.message }, 'error');
+          return;
+        }
+
+        // join
+        if (!this.topics[topic]) {
+          this.topics[topic] = new Set();
+        }
+        this.topics[topic].add(socket);
+
+        reply(socket, topic, `chan_reply_${ref}`);
+        this.emit('channel.join', { socket, topic, event, payload });
+
+        // post hook
+        try {
+          await this.hooks.postJoinChannel({ joinRef, ref, topic, event, payload });
+        } catch (error) {
+          this.logger.error('postJoinChannel error', { error });
+        }
+
+        return;
+      }
+
+      if (event === 'phx_leave') {
+        // pre hook
+        try {
+          await this.hooks.preLeaveChannel({ joinRef, ref, topic, event, payload });
+        } catch (error) {
+          this.logger.error('preLeaveChannel error', { error });
+          reply(socket, topic, `chan_reply_${ref}`, { message: error.message }, 'error');
+          return;
+        }
+
+        // leave
+        this._leaveChannel(socket, topic);
+        reply(socket, topic, `chan_reply_${ref}`);
+
+        // post hook
+        try {
+          await this.hooks.postLeaveChannel({ joinRef, ref, topic, event, payload });
+        } catch (error) {
+          this.logger.error('postLeaveChannel error', { error });
+        }
+
+        return;
+      }
+
+      // pre hook
+      try {
+        await this.hooks.receiveMessage({ socket, joinRef, ref, topic, event, payload });
+      } catch (error) {
+        this.logger.error('receiveMessage error', { error });
+        reply(socket, topic, `chan_reply_${ref}`, { message: error.message }, 'error');
+        return;
+      }
+
+      reply(socket, topic, `chan_reply_${ref}`, {});
+    });
+
+    socket.on('close', () => {
+      this.logger.debug('socket onclose', { id: socket.id });
+
+      Object.keys(this.topics).forEach((topic) => this._leaveChannel(socket, topic));
+    });
+
+    socket.on('error', (err) => {
+      this.logger.error('socket onerror', { id: socket.id, error: err });
+      Object.keys(this.topics).forEach((topic) => this._leaveChannel(socket, topic));
+    });
+  }
+
+  /**
+   * private
+   */
+  onWssClose() {
+    this.logger.debug('ws server onclose');
+    this.emit('close');
+  }
+
+  /**
+   * private
+   */
+  onWssError(error) {
+    this.logger.error('ws server error', { error });
+    this.emit('error', error);
+  }
+
+  _leaveChannel(socket, topic) {
+    // unsubscribe
+    if (this.topics[topic]) {
+      this.topics[topic].delete(socket);
+    }
+
+    this.emit('channel.leave', { socket, topic });
+    if (!this.topics[topic] || !this.topics[topic].size) {
+      this.emit('channel.destroy', { socket, topic });
+    }
+  }
+}
+
+module.exports = WsServer;

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@arcblock/ws",
+  "version": "1.6.10",
+  "description": "OCAP Chain websocket server and client",
+  "keywords": [
+    "websocket"
+  ],
+  "author": "arcblock <engineer@arcblock.io>",
+  "homepage": "https://github.com/ArcBlock/asset-chain#readme",
+  "license": "Apache-2.0",
+  "main": "./lib/index.js",
+  "browser": "./lib/browser.js",
+  "directories": {
+    "lib": "lib",
+    "test": "__tests__"
+  },
+  "files": [
+    "lib"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArcBlock/asset-chain.git"
+  },
+  "scripts": {
+    "lint": "eslint tests lib",
+    "lint:fix": "eslint --fix tests lib",
+    "test": "jest --forceExit --detectOpenHandles",
+    "coverage": "npm run test -- --coverage"
+  },
+  "bugs": {
+    "url": "https://github.com/ArcBlock/asset-chain/issues"
+  },
+  "dependencies": {
+    "@arcblock/event-hub": "1.6.10",
+    "debug": "^4.3.3",
+    "eventemitter3": "^4.0.4",
+    "phoenix": "1.5.12",
+    "uuid": "^8.3.0",
+    "ws": "^8.2.2"
+  },
+  "devDependencies": {
+    "get-port": "^5.1.1"
+  },
+  "gitHead": "ab272e8db3a15c6571cc7fae7cc3d3e0fdd4bdb1"
+}