node-ws-packets

A packet-based javascript websocket communitcation.

About

To simplify and streamline the process of handling, sending and receiving data, node-ws-packets was created. It's useful for live communitaction between multiple clients, like in browser games.

Packets are validated with Node Data Validator. If a packet fails validation (model and payload fail to compare) the packet will be dropped!

There are 2 main components to this module. The handlers (Client or Server) and the packets. Packets are created from a base packet class that handels validation and some base functionality. The handlers handle incoming packets and execute them, if the payload data matches the local defined model. The Model is not transmitted over the network.

The server handler also handels client id generation for identification of clients. The uuid module is used for this id generation.

Installation

NodeJS Installation

npm i node-ws-packets

Browser Support

For browser support we pre-packed the Client.js and Packet.js. You can import the file below into your html project and use it like you would in a node environment. Note: The Server is not available in this script. Further - you can use the module with webpack and we recommend to do so.

1<script src="https://unpkg.com/node-ws-packets@latest/Browser.js" type="text/javascript"></script>

Usage

Import

with Common JS

1/* Import Classes */
2const { Packet, Server, Client } = require("node-ws-packets");

or - TypeScript Import

1/* Import Classes */
2import { Packet, Server, Client } from "node-ws-packets";

Using the Module

Creating server instance

1/*
2    IMPORTS
3*/
4const { Server } = require("node-ws-packets");
5
6/*
7    Create Server
8*/
9// Active WebSocketServer needed.
10const serverManager = new Server(wss, { log: true, keepAlive: true, keepAliveTimeout = 60, keepAliveInterval = 30 });
11
12/*
13    Add Packets
14*/
15serverManager.addPacket(new Ping());
16
17/*
18    Add Events
19*/
20
21// Executed on every client that connects
22serverManager.onConnect((ws) => {
23    // Send Test Packet after client connected
24    ws.sendPacket(new Ping({timestamp: Date.now()}));
25});
26
27// Executed on every client that disconnects
28serverManager.onDisconnect((ws, event) => {
29    console.log("server", "Client has disconnected!");
30});
31
32// Executed on every error that a client encounters
33serverManager.onError((ws, error) => {
34    console.log(ws.id, error);
35});
36
37// Executed on every invalid packet or message
38serverManager.onInvalid((ws, data) => {
39    console.log(ws.id, data);
40});
41
42/*
43    Broadcast Packets to all connected clients
44*/
45serverManager.broadcast(/*Packet*/);

Creating client instance

1/*
2    IMPORTS
3*/
4const { Client } = require("node-ws-packets");
5
6/*
7    Client
8*/
9// Active Web Socket Connection needed.
10const clientManager = new Client(ws, { log: true, keepAlive: true });
11
12/*
13    Add Packets
14*/
15clientManager.addPacket(new Ping());
16
17/*
18    Add Events
19*/
20
21// Executed on client connection
22clientManager.onConnect((ws) => {
23    // Same as Server Manager
24});
25
26// Executed on client disconnect
27clientManager.onDisconnect((ws, event) => {
28    // Same as Server Manager
29});
30
31// Executed on client error
32clientManager.onError((ws, error) => {
33    // Same as Server Manager
34});
35
36// Executed on every invalid packet or message
37clientManager.onInvalid((ws, data) => {
38    // Same as Server Manager
39});
40

Wrapper Function

ws.sendPacket(new Packet) is a wrapper for sending packets directrly from the WebSocket connection. It is implemented on client and server WebSocket connections. Using ws.send can break the sending and receiving of packets.

Creating a packet

1/*
2    IMPORTS
3*/
4const { Packet } = require("node-ws-packets");
5
6/*
7    Create Packet
8*/
9class Ping extends Packet {
10    constructor(payload) {
11
12        /*
13            Create Model
14            Used to check data types
15            [Dependency Package node-data-validator used]
16        */
17        const model = {
18            timestamp: Number
19        }
20
21        /*
22            Init Packet
23        */
24        super("Ping", payload, model);
25    }
26
27    /**
28     * Handle packet
29     * @param {object} ws websocket connection
30     */
31    handle(ws) {
32        console.log(this.payload);
33    }
34}

About message handling

If a packet was registered via .addPacket(new ExamplePacket());, its handle()-function gets called on the receiving side. Note that the model has to be the exact same on both Client and Server, but the handle functions can differ (e.g. writing messages into a db on the Server and outputting the message on the Client).

Options

A Server or Client can accept the following options.

Option	Type	Description	Values	Default
log	boolean	Should the Module auto-log to console?	true or false	false
keepAlive	boolean	Send an integrated Ping Message to the clients to keep the connection alive	true or false	false
keepAliveTimeout	number	Time a ping packet has to return before the connection is forcefully closed	any number	60
keepAliveInterval	number	Time until the next Ping Message is sent to the client after receiving the latest Ping	any number	30

Packet

A packet is always structured in the same way.

1PacketName {
2  name: 'PacketName',
3  payload: { PacketData },
4  model: { PacketModel },
5  isValid: true,
6  sender: SenderID
7}

IDs

IDs are generated by the server for each client. You can get the id of an client with ws.id. It is recommended to implement a handshake protocol with this id and save it on the client locally.

Request Parameters

WebSocket Connections can carry additional parameters in the query. These parameters are passed on to the WebSocket Client object and can be accessed with ws.req.query. These are auto generated from the url string in ws.req.url.

ws.req contains the whole request object.

About OnConnect

If you want to create a client manager, you can hook in the user id on the onConnect callback on the server side. With the aforementioned ws.id you can initiate a new client instance on your client manager.