Merge pull request #26 from AnujPanthri/server-comments

server/src/helpers.ts

@@ -1,6 +1,12 @@
 import * as crypto from "crypto";
 import basex from "base-x";
 
+/**
+ * Generates a random, cryptographically secure token using uppercase, readable characters.
+ * Characters that are used: ABCDEFGHJKMNPQRSTUVWXYZ23456789
+ * @param {number} length - length of the token
+ * @returns {string}
+ */
 export function generateSessionToken(length: number): string {
     if (length < 1) throw new Error("invalid length. length must be greater than 0");
     const base31Tokens = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";

server/src/index.ts

@@ -1,3 +1,8 @@
+/*
+Created by Anne Lefebvre and Anuj Panthri - 2023
+Handles the HTTP file serving and the WebSocket connect for HapticTouch
+*/
+
 import express, { Application, Request, Response } from "express";
 import * as http from "http";
 import * as WebSocket from "ws";
@@ -7,6 +12,7 @@ import WebSocketWrapper from "./socket/WebSocketAdapter";
 import pino from "pino";
 import path from "path";
 
+// If started with --silent, then logging will be disabled.
 (() => {
     const args = process.argv;
     if (args.includes("--silent")) {
@@ -16,6 +22,10 @@ import path from "path";
     return main(true);
 })();
 
+/**
+ * Starts HTTP(S) and WS server, initializes HapticLinkServer and handles routing.
+ * @param {boolean} logging - Defaults true
+ */
 function main(logging: boolean = true) {
     const port: number = parseInt(process.env.PORT as string, 10) || 3000;
     const logger = pino({
@@ -35,8 +45,10 @@ function main(logging: boolean = true) {
     const server = http.createServer(app);
     const wss = new WebSocket.Server({ server });
 
+    // The entire build/web directory is statically served.
     app.use(express.static(path.join(__dirname, "../../client/build/web")));
 
+    // Catch all. If we want to add pages later, then we should probably change this.
     app.get("*", (_req: Request, res: Response) => {
         res.sendFile(path.join(__dirname + "/../../client/build/web/index.html"));
     });

server/src/socket/hapticLinkServer.ts

@@ -5,9 +5,15 @@ import { WebSocketInterface } from "./WebSocketAdapter";
 
 type RouteHandler<T> = (context: Context<T>) => void;
 
+
 export interface Route<T> {
+    // Name of route
     name: string;
+    
+    // ZodSchema used to validate request body
     schema: ZodSchema<T>;
+
+    // Handler Function. To be called after request body is validated
     handler: RouteHandler<T>;
 }
 
@@ -25,6 +31,7 @@ export class User {
     }
 }
 
+// Context holds all available information for any given request
 export interface Context<T> {
     ws: WebSocketInterface;
     user: User;
@@ -33,8 +40,13 @@ export interface Context<T> {
 }
 
 export class HapticLinkServer {
+    // Router map
     routes: { [key: string]: Route<any> };
+
+    // All rooms are stored in this map
     rooms: { [key: string]: Room };
+
+    // All users are stored in this map and should be dropped when their connection does.
     users: Map<WebSocketInterface, User>;
 
     constructor() {
@@ -43,6 +55,11 @@ export class HapticLinkServer {
         this.rooms = {};
     }
 
+    /**
+     * Removes user from registered users
+     * @param {WebSocketInterface} ws 
+     * @returns {boolean} true/false whether the user was successfully removed
+     */
     removeUser(ws: WebSocketInterface): boolean {
         const user = this.users.get(ws);
         if (!user) return false;
@@ -52,6 +69,13 @@ export class HapticLinkServer {
         return true;
     }
 
+    /**
+     * Registers a route with router
+     * @param {string} name The name of the route which be used by the client to identify the route.
+     * @param {ZodSchema<T>} schema A ZodSchema to match the body of the WS message
+     * @param {RouteHandler<T>} handler A handler function that should have a matching schema
+     * @returns 
+     */
     addRoute<T>(name: string, schema: ZodSchema<T>, handler: RouteHandler<T>): boolean {
         if (name in this.routes) {
             return false;
@@ -66,6 +90,14 @@ export class HapticLinkServer {
         return true;
     }
 
+    /**
+     * Compares message param with names of registered routes
+     * If route exists, validates the schema and then calls
+     * the handler function with the formatted payload
+     * @param {WebSocketInterface} ws
+     * @param {string} message WebSocket message
+     * @returns 
+     */
     handleRoute(ws: WebSocketInterface, message: string) {
         // Parse JSON
         let payload: any;
@@ -75,19 +107,23 @@ export class HapticLinkServer {
             return ws.send(JSON.stringify({ error: "message not in JSON format" }));
         }
 
+        // Check if message includes route
         if (typeof payload != "object" || !Object.keys(payload).includes("route")) {
             return ws.send(JSON.stringify({ error: "missing route" }));
         }
 
+        // Check if route is registered
         if (!(payload.route in this.routes)) {
             return ws.send(JSON.stringify({ error: "route not found" }));
         }
 
         const route = this.routes[payload.route];
+        // Removes route from body
         delete payload.route;
 
         let user: User;
 
+        // Get user or create new one
         if (this.users.has(ws)) {
             user = this.users.get(ws)!;
         } else {
@@ -96,6 +132,7 @@ export class HapticLinkServer {
             user = newUser;
         }
 
+        // Create context
         let context: Context<any> = {
             ws,
             payload,
@@ -107,6 +144,7 @@ export class HapticLinkServer {
             return ws.send(JSON.stringify({ error: "invalid route" }));
         }
 
+        // Validates message body and calls handler
         if (route.schema.safeParse(payload).success) {
             route.handler(context);
         } else {

server/src/socket/room.ts

@@ -1,6 +1,7 @@
 import { generateSessionToken } from "../helpers";
 import { User } from "./hapticLinkServer";
 
+// User data that is safe to reveal to users
 export interface UserData {
     username: string;
     id: string;
@@ -12,18 +13,34 @@ export class Room {
     static roomIdLength: number = 6;
     id: string;
     users: User[];
+
+    /**
+     * @constructor
+     * @param roomId Optional, a secure one will be generated
+     */
     constructor(roomId?: string) {
         this.id = roomId || generateSessionToken(Room.roomIdLength);
         this.users = [];
     }
 
+    /**
+     * Add a user to room, broadcasts message to all room users
+     * when user if user is successfully added. Won't add user
+     * if they are alreadu part of it
+     * @param {User} user
+     * @returns 
+     */
     addUser(user: User) {
-        // Generate random roomId if one wasn't created.
         if (this.users.includes(user)) return;
         this.users.push(user);
         this.updateRoom();
     }
 
+    /**
+     * Removed user from an ID 
+     * @param {string} id User's ID
+     * @returns {boolean} true/false whether the user was deleted or not
+     */
     removeUserById(id: string): boolean {
         const oldSize = this.users.length;
         this.users = this.users.filter((user) => user.id != id);
@@ -31,13 +48,19 @@ export class Room {
         return oldSize > this.users.length;
     }
 
+    /**
+     * Used to check if a room contains a user 
+     * @param {string} id User's ID
+     * @returns {boolean} true/false whether the room has that user
+     */
     hasUser(id: string): boolean {
         return this.users.some((user) => user.id == id);
     }
 
     /**
-     * @param message Message to send to users
-     * @param filter Array of user ID to ignore when sending
+     * Broadcasts a message to every user in room
+     * @param {string} message Message to send to users
+     * @param {string[]} filter Array of user ID to ignore when sending
      **/
     broadcast(message: string, filter: string[] = []) {
         this.users.forEach((user) => {
@@ -46,6 +69,10 @@ export class Room {
         });
     }
 
+    /**
+     * Broadcasts the user list of the current room.
+     * Should be used when a user is added or removed.
+     */
     updateRoom() {
         const usersData: UserData[] = [];
         this.users.forEach((user) => {

server/src/socket/routes.ts

@@ -6,6 +6,10 @@ import { SendVibrationHandler, SendVibrationSchema } from "./routes/send_touch";
 import { SetUsernameHandler, SetUsernameSchema } from "./routes/set_username";
 import { TestConnnectionSchema, TestConnectionHandler } from "./routes/test_connection";
 
+/**
+ * Registers all the routes for Haptic Link
+ * @param {HapticLinkServer} router
+ */
 export function registerRoutes(router: HapticLinkServer) {
     router.addRoute("test_connection", TestConnnectionSchema, TestConnectionHandler);
     router.addRoute("join_room", JoinRoomSchema, JoinRoomHandler);