WebSocket Server & Client
This is still a work in progress and very much in the early stages of development. Features & code are subject to change as I continue to build my knowledge in this area.
Installation
yarn add ws-server-client
or
npm install ws-server-client
Getting Started
Add the following to your package.json
"scripts": {
"start": "node ./node_modules/ws-server-client/start.js"
},
Create a .env file in the root directory of your project
APP_PORT=21000
APP_ENV=local
APP_HOST=127.0.0.1
APP_SCHEME=http
APP_KEY=changeme
CORS_HEADERS=
CORS_ORIGIN=
CORS_METHODS=
CORS_CREDENTIALS=
STORAGE_DRIVER=redis
SESSION_DRIVER=memory
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_UNIX_PATH=
Configuration
Here are a full list of all supported configuration options.
Name | .env Name | Type | Default | Description |
---|---|---|---|---|
app.env | APP_ENV | Number | local | The environment the application is currently running on. |
app.port | APP_PORT | Number | 21000 | The port which the server listens to connections on. |
app.key | APP_KEY | String | changeme | The key used for sessions and other forms of encryption. |
app.host | APP_HOST | String | 127.0.0.1 | The host which the server listens to connections on. |
app.scheme | APP_SCHEME | String | http | The scheme/protocol which the server listens to connections on. |
client.url | CLIENT_URL | String | http://localhost | The base URL of the client where the connection is made from. |
api.url | API_URL | String | http://localhost | The base URL for the API endpoints. |
auth.endpoints.user.url | String | null | The endpoint to retrieve the authenticated user. | |
auth.endpoints.user.property | String | data | The property to pull the user data from the response. | |
cors.headers | CORS_HEADERS | String | * | The cross-site headers allowed. |
cors.origin | CORS_ORIGIN | String | * | The cross-site origin allowed. |
cors.methods | CORS_METHODS | String | * | The cross-site methods allowed. |
cors.credentials | CORS_CREDENTIALS | Boolean | true | The cross-site credentials allowed. |
storage.driver | STORAGE_DRIVER | String | redis | The driver to determine the type of storage system. Supported values: redis |
storage.prefix | String | <app.env>_ | The prefix applied on all storage values. | |
session.driver | SESSION_DRIVER | String | memory | The driver to determine the type of session system. Supported values: memory, redis |
session.expiry | String | 60 | The expiry time for each session in minutes. | |
redis.host | REDIS_HOST | String | 127.0.0.1 | The host for establishing the redis connection. |
redis.port | REDIS_PORT | Number | 6379 | The port for establishing the redis connection. |
redis.password | REDIS_PASSWORD | String | null | The password for authentication when establishing the redis connection. |
redis.unix_path | REDIS_UNIX_PATH | String | null | The unix socket path for establishing the redis connection. |
Events
Initial setup
Create your event classes in an events
directory at the root of your project and the server will automatically import these.
- The
listen(socket, payload)
method MUST be implemented to handle the event and return data back. This method can return a number, object, array or string. \ - The
authorize(socket, payload)
method can be implemented to determine where the socket is authorized. Defaults to true if not specified. This method must return a boolean. - The
namespace()
method can be implemented to specify which namespace to restrict the event to. This method must return a string.
const { Event } = require('ws-server-client');
class ExampleEvent extends Event {
authorize(socket, payload) {
return true;
};
listen(socket, payload) {
return { example: 'This is an example data response.' };
};
namespace() {
return 'ExampleNamespace';
};
};
module.exports = ExampleEvent;
The storage instance can be used to set and get values through your selected storage driver (Only redis is currently supported)
this.storage.set('example-key', 'example-value').then(...).catch(...);
this.storage.get('example-key').then((value) => ...).catch(...);
The config instance can be used to get configuration values. The key specified uses dot-notation.
this.config.get('app.env');
Send to server
All events will be sent to the server using the Socket IO client library.
io.emit('ExampleEvent', { example: 'Example payload.'}, data => {});
Namespaces
Initial setup
Create your namespace classes in a namespaces
directory at the root of your project and the server will automatically import these.
- The
authorize(socket, { query })
method can be implemented to determine whether the socket is authorized to connect. Defaults to true if not specified. This method must return a boolean. - The
connect(socket, { query })
method can be implemented to handle a new socket connection. This method doesn't have to return anything. - The
disconnect(socket)
method can be implemented to handle a socket being disconnected. This method doesn't have to return anything.
const { Namespace } = require('ws-server-client');
class ExampleNamespace extends Namespace {
authorize(socket, { query }) {
return true;
};
connect(socket, { query }) {
socket.emit('InitialData', { example: 'Example payload if you want to send the client initial data.' });
};
disconnect(socket) {};
};
module.exports = ExampleNamespace;