From ad057916d85a5d5f852b426354a12d8cc796482c Mon Sep 17 00:00:00 2001 From: rainbow napkin Date: Tue, 26 Aug 2025 08:37:49 -0400 Subject: [PATCH] Continued work on JSDoc for src/app --- src/app/channel/activeChannel.js | 29 ++++++++++++- src/app/channel/channelManager.js | 67 +++++++++++++++++++++++++++++-- src/app/channel/chat.js | 4 +- src/app/channel/chatBuffer.js | 4 +- 4 files changed, 96 insertions(+), 8 deletions(-) diff --git a/src/app/channel/activeChannel.js b/src/app/channel/activeChannel.js index 1e62f42..a3bbd8c 100644 --- a/src/app/channel/activeChannel.js +++ b/src/app/channel/activeChannel.js @@ -21,7 +21,16 @@ const queue = require('./media/queue'); const channelModel = require('../../schemas/channel/channelSchema'); const playlistHandler = require('./media/playlistHandler') +/** + * Class representing a single active channel + */ module.exports = class{ + + /** + * Instantiates an activeChannel object + * @param {channelManager} server - Parent Server Object + * @param {Mongoose.Document} chanDB - chanDB to rehydrate buffer from + */ constructor(server, chanDB){ this.server = server; this.name = chanDB.name; @@ -34,6 +43,13 @@ module.exports = class{ this.chatBuffer = new chatBuffer(server, chanDB, this); } + + /** + * Handles server-side initialization for new connections to the channel + * @param {Mongoose.Document} userDB - User Document Passthrough to save on DB Access + * @param {Mongoose.Document} chanDB - Channnel Document Passthrough to save on DB Access + * @param {Socket} socket - Requesting Socket + */ async handleConnection(userDB, chanDB, socket){ //get current user object from the userlist var userObj = this.userList.get(userDB.user); @@ -69,7 +85,11 @@ module.exports = class{ this.broadcastUserList(socket.chan); } - handleDisconnect(socket, reason){ + /** + * Handles server-side initialization for disconnecting from the channel + * @param {Socket} socket - Requesting Socket + */ + handleDisconnect(socket){ //If we have more than one active connection if(this.userList.get(socket.user.user).sockets.length > 1){ //temporarily store userObj @@ -91,6 +111,9 @@ module.exports = class{ this.broadcastUserList(socket.chan); } + /** + * Broadcasts user list to all users + */ broadcastUserList(){ //Create a userlist object with the tokebot user pre-loaded var userList = [{ @@ -110,6 +133,10 @@ module.exports = class{ this.server.io.in(this.name).emit("userList", userList); } + /** + * Broadcasts channel emote list to connected users + * @param {Mongoose.Document} chanDB - Channnel Document Passthrough to save on DB Access + */ async broadcastChanEmotes(chanDB){ //if we wherent handed a channel document if(chanDB == null){ diff --git a/src/app/channel/channelManager.js b/src/app/channel/channelManager.js index c4a623f..2cdf3ea 100644 --- a/src/app/channel/channelManager.js +++ b/src/app/channel/channelManager.js @@ -26,9 +26,15 @@ const loggerUtils = require('../../utils/loggerUtils'); const csrfUtils = require('../../utils/csrfUtils'); const activeChannel = require('./activeChannel'); const chatHandler = require('./chatHandler'); -//const mediaYanker = require('./media/yanker'); +/** + * Class containing global server-side channel connection management logic + */ module.exports = class{ + /** + * Instantiates object containing global server-side channel conection management logic + * @param {Server} io - Socket.io server instanced passed down from server.js + */ constructor(io){ //Set the socket.io server this.io = io; @@ -44,6 +50,10 @@ module.exports = class{ io.on("connection", this.handleConnection.bind(this) ); } + /** + * Handles global server-side initialization for new connections to any channel + * @param {Socket} socket - Requesting Socket + */ async handleConnection(socket){ try{ //ensure unbanned ip and valid CSRF token @@ -92,6 +102,11 @@ module.exports = class{ } } + /** + * Global server-side validation logic for new connections to any channel + * @param {Socket} socket - Requesting Socket + * @returns {Boolean} true on success + */ async validateSocket(socket){ //If we're proxied use passthrough IP const ip = config.proxied ? socket.handshake.headers['x-forwarded-for'] : socket.handshake.address; @@ -129,6 +144,11 @@ module.exports = class{ return true; } + /** + * Global server-side authorization logic for new connections to any channel + * @param {Socket} socket - Requesting Socket + * @returns {Mongoose.Document} - Authorized User Document upon success + */ async authSocket(socket){ //Find the user in the Database since the session won't store enough data to fulfill our needs :P const userDB = await userModel.findOne({user: socket.request.session.user.user}); @@ -146,9 +166,14 @@ module.exports = class{ return userDB; } + /** + * Gets active channel from a given socket + * @param {Socket} socket - Socket to check + * @returns {Object} Object containing users active channel name and channel document object + */ async getActiveChan(socket){ socket.chan = socket.handshake.headers.referer.split('/c/')[1].split('/')[0]; - const chanDB = (await channelModel.findOne({name: socket.chan})) + const chanDB = (await channelModel.findOne({name: socket.chan})); //Check if channel exists if(chanDB == null){ @@ -166,24 +191,42 @@ module.exports = class{ //Return whatever the active channel is (new or old) return {activeChan, chanDB}; - //return activeChan; } + /** + * Define Global Server-Side socket event listeners + * @param {Socket} socket - Socket to check + */ defineListeners(socket){ //Socket Listeners socket.conn.on("close", (reason) => {this.handleDisconnect(socket, reason)}); } + /** + * Global server-side logic for handling disconncted sockets + * @param {Socket} socket - Socket to check + * @param {String} reason - Reason for disconnection + */ handleDisconnect(socket, reason){ var activeChan = this.activeChannels.get(socket.chan); activeChan.handleDisconnect(socket, reason); } + /** + * Pulls user information by socket + * @param {Socket} socket - Socket to check + * @return returns related user info + */ getSocketInfo(socket){ const channel = this.activeChannels.get(socket.chan); return channel.userList.get(socket.user.user); } + /** + * Pulls user information by socket + * @param {Socket} socket - Socket to check + * @return returns related user info + */ getConnectedChannels(socket){ //Create a list to hold connected channels var chanList = []; @@ -203,6 +246,11 @@ module.exports = class{ return chanList; } + /** + * Iterates through connections by a given username, and runs them through a given callback function/method + * @param {String} user - Username to crawl connections against + * @param {Function} cb - Callback function to run active connections of a given user against + */ crawlConnections(user, cb){ //For each channel this.activeChannels.forEach((channel) => { @@ -216,6 +264,11 @@ module.exports = class{ }); } + /** + * Iterates through connections by a given username, and runs them through a given callback function/method + * @param {String} user - Username to crawl connections against + * @param {Function} cb - Callback function to run active connections of a given user against + */ getConnections(user){ //Create a list to store our connections var connections = []; @@ -228,11 +281,19 @@ module.exports = class{ return connections; } + /** + * Kicks a user from all channels by username + * @param {String} user - Username to kick from the server + * @param {String} reason - Reason for kick + */ kickConnections(user, reason){ //crawl through connections and kick user this.crawlConnections(user,(foundUser)=>{foundUser.disconnect(reason)}); } + /** + * Broadcast global emote list + */ async broadcastSiteEmotes(){ //Get emote list from DB const emoteList = await emoteModel.getEmotes(); diff --git a/src/app/channel/chat.js b/src/app/channel/chat.js index 064c51f..5a181c8 100644 --- a/src/app/channel/chat.js +++ b/src/app/channel/chat.js @@ -19,9 +19,9 @@ along with this program. If not, see .*/ */ class chat{ /** - * + * Instantiates a chat message object * @param {connectedUser} user - User who sent the message - * @param {string} flair - Flair ID String for the flair used to send the message + * @param {String} flair - Flair ID String for the flair used to send the message * @param {Number} highLevel - Number representing current high level * @param {String} msg - Contents of the message, with links replaced with numbered file-seperator markers * @param {String} type - Message Type Identifier, used for client-side processing. diff --git a/src/app/channel/chatBuffer.js b/src/app/channel/chatBuffer.js index bc39c94..a60bcab 100644 --- a/src/app/channel/chatBuffer.js +++ b/src/app/channel/chatBuffer.js @@ -23,7 +23,7 @@ class chatBuffer{ /** * Instantiates a new chat buffer for a given channel * @param {channelManager} server - Parent Server Object - * @param {Document} chanDB - chanDB to rehydrate buffer from + * @param {Mongoose.Document} chanDB - chanDB to rehydrate buffer from * @param {activeChannel} channel - Parent Channel Object */ constructor(server, chanDB, channel){ @@ -98,7 +98,7 @@ class chatBuffer{ /** * Saves RAM-Based buffer to Channel Document in DB * @param {String} reason - Reason for DB save, formatted as 'x minutes/seconds of in/activity', used for logging purposes - * @param {Document} chanDB - Channel Doc to work with, can be left empty for method to auto-find through channel name. + * @param {Mongoose.Document} chanDB - Channel Doc to work with, can be left empty for method to auto-find through channel name. */ async saveDB(reason, chanDB){ //clear existing timers