| 1 |
|
| 2 | # Chat service
|
| 3 |
|
| 4 | [](https://travis-ci.org/an-sh/chat-service)
|
| 5 | [](https://coveralls.io/github/an-sh/chat-service?branch=master)
|
| 6 | [](https://david-dm.org/an-sh/chat-service)
|
| 7 |
|
| 8 | Server side chat based on top of socket.io focused on scalability and
|
| 9 | extensibility.
|
| 10 |
|
| 11 |
|
| 12 | ### Features
|
| 13 |
|
| 14 | - Simple network layer using socket.io and json based messages.
|
| 15 | - Room and user2user chatting with permissions management.
|
| 16 | - Allows a single user to have multiple connected sockets.
|
| 17 | - Runs as a stateless service with built-in Redis state storage.
|
| 18 | - Can be extened via command hooks.
|
| 19 | - Can use external state storage implementations.
|
| 20 | - Extensive unit test coverage (95%+).
|
| 21 |
|
| 22 |
|
| 23 | ### Basic usage
|
| 24 |
|
| 25 | ```javascript
|
| 26 | var chatServer = new ChatService({ port : port },
|
| 27 | { auth : auth, onConnect : onConnect },
|
| 28 | 'redis');
|
| 29 | ```
|
| 30 | Here we have created a new server instance. It is ruuning _`port`_
|
| 31 | according to options argument. The second argument represents hooks,
|
| 32 | that will run during server lifetime. _`auth`_ hook is simular to the
|
| 33 | one that is described in socket.io documentation, and _`onConnect`_
|
| 34 | hook will run when client is connected. These hook are intended for
|
| 35 | integration to existing user authentication systems. The last argument
|
| 36 | is a state storage.
|
| 37 |
|
| 38 | Connection from a client side is trivial:
|
| 39 | ```javascript
|
| 40 | socket = ioClient.connect(url1, params);
|
| 41 | socket.on('loginConfirmed', function(username) {
|
| 42 | // code
|
| 43 | });
|
| 44 | ```
|
| 45 | A conneted client can send `UserCommands` to a server:
|
| 46 | ```javascript
|
| 47 | socket.emit('roomJoin', 'someRoom', function(error, data) {
|
| 48 | // code
|
| 49 | });
|
| 50 | ```
|
| 51 | A server reply is send as a socket.io ack and has a standart node
|
| 52 | (error, data) callback arguments format. Semantics of most commands is
|
| 53 | very straitforward and simple. Only for room commands a client must
|
| 54 | join a room to succesfully execute them.
|
| 55 |
|
| 56 | ```javascript
|
| 57 | socket.on('roomMessage', function(room, user, msg) {
|
| 58 | });
|
| 59 | ```
|
| 60 | Also a server will send `ServerMessages`. Note that these messages
|
| 61 | don't require any reply.
|
| 62 |
|
| 63 |
|
| 64 | ### Documentation
|
| 65 |
|
| 66 | Run `npm install -g codo` and `codo` to generate documentation. Public
|
| 67 | API consists of public methods of the following classes:
|
| 68 |
|
| 69 | - Class: `ServerMessages` - represents socket.io messages sent from a
|
| 70 | server to a client. No client reply is requered.
|
| 71 | - Class: `UserCommands` - represents socket.io messages sent from a
|
| 72 | client to a server. Server will send back a socket.io ack reply with
|
| 73 | (error, data) arguments.
|
| 74 | - Class: `ChatService` - is a server instance.
|
| 75 | - Class: `Room` - represents a room.
|
| 76 | - Class: `User` - represents an user.
|
| 77 |
|
| 78 | Look in the test directory, for socket.io-client messages, server
|
| 79 | setup and hooks usage.
|
| 80 |
|
| 81 |
|
| 82 | ### TODO
|
| 83 |
|
| 84 | - API for adding custom messages.
|
| 85 |
|
| 86 |
|
| 87 | ### License
|
| 88 |
|
| 89 | MIT
|