From c6c456c253426242bd16d95329d120a447f0674f Mon Sep 17 00:00:00 2001 From: Hri7566 Date: Sat, 13 Jul 2024 14:45:51 -0400 Subject: [PATCH] Document --- src/ws/Socket.ts | 139 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 138 insertions(+), 1 deletion(-) diff --git a/src/ws/Socket.ts b/src/ws/Socket.ts index 4b78029..85a790e 100644 --- a/src/ws/Socket.ts +++ b/src/ws/Socket.ts @@ -123,18 +123,36 @@ export class Socket extends EventEmitter { })(); } + /** + * Get the IP of this socket + * @returns IP address + **/ public getIP() { return this.ip; } + /** + * Get the user ID of this socket + * @returns User ID + **/ public getUserID() { return this._id; } + /** + * Get the participant ID of this socket + * @returns Participant ID + **/ public getParticipantID() { return this.id; } + /** + * Move this participant to a channel + * @param _id Target channel ID + * @param set Channel settings, if the channel is instantiated + * @param force Whether to make this socket join regardless of channel properties + **/ public setChannel(_id: string, set?: Partial, force = false) { // Do we exist? if (this.isDestroyed()) return; @@ -190,6 +208,9 @@ export class Socket extends EventEmitter { public admin = new EventEmitter(); + /** + * Bind the message handlers to this socket (internal) + **/ private bindEventListeners() { for (const group of eventGroups) { if (group.id == "admin") { @@ -205,6 +226,10 @@ export class Socket extends EventEmitter { } } + /** + * Send this socket an array of messages + * @param arr Array of messages to send + **/ public sendArray( arr: ClientEvents[EventID][] ) { @@ -212,6 +237,9 @@ export class Socket extends EventEmitter { this.ws.send(JSON.stringify(arr)); } + /** + * Load this socket's user data + **/ private async loadUser() { let user = await readUser(this._id); @@ -230,6 +258,10 @@ export class Socket extends EventEmitter { this.user = user; } + /** + * Get this socket's user data + * @returns User data + **/ public getUser() { if (this.user) { return this.user; @@ -238,6 +270,10 @@ export class Socket extends EventEmitter { return null; } + /** + * Get this socket's user flags + * @returns User flag object + **/ public getUserFlags() { if (this.user) { try { @@ -250,6 +286,11 @@ export class Socket extends EventEmitter { } } + /** + * Set a user flag on this socket + * @param key ID of user flag to change + * @param value Value to change the user flag to + **/ public async setUserFlag(key: keyof UserFlags, value: unknown) { if (this.user) { try { @@ -267,6 +308,10 @@ export class Socket extends EventEmitter { } } + /** + * Get this socket's participant data + * @returns Participant object + **/ public getParticipant() { if (this.user) { const flags = this.getUserFlags(); @@ -291,6 +336,9 @@ export class Socket extends EventEmitter { private destroyed = false; + /** + * Forcefully close this socket's connection and remove them from the server + **/ public destroy() { // Socket was closed or should be closed, clear data // logger.debug("Destroying UID:", this._id); @@ -315,10 +363,18 @@ export class Socket extends EventEmitter { this.destroyed = true; } + /** + * Test if this socket is destroyed + * @returns Whether this socket is destroyed + **/ public isDestroyed() { return this.destroyed == true; } + /** + * Get this socket's current cursor position + * @returns Cursor position object + **/ public getCursorPos() { if (!this.cursorPos) this.cursorPos = { @@ -328,6 +384,11 @@ export class Socket extends EventEmitter { return this.cursorPos; } + /** + * Set this socket's current cursor position + * @param x X coordinate + * @param y Y coordinate + **/ public setCursorPos(x: CursorValue, y: CursorValue) { if (typeof x == "number") { x = x.toFixed(2); @@ -357,12 +418,18 @@ export class Socket extends EventEmitter { ch.emit("cursor", pos); } + /** + * Get the channel this socket is in + **/ public getCurrentChannel() { return ChannelList.getList().find( ch => ch.getID() == this.currentChannelID ); } + /** + * Send this socket a channel update message + **/ public sendChannelUpdate(ch: IChannelInfo, ppl: Participant[]) { this.sendArray([ { @@ -374,6 +441,12 @@ export class Socket extends EventEmitter { ]); } + /** + * Change this socket's name/color + * @param name Desired name + * @param color Desired color + * @param admin Whether to force this change + **/ public async userset( name?: string, color?: string, @@ -417,6 +490,10 @@ export class Socket extends EventEmitter { } } + /** + * Set a list of rate limits on this socket + * @param list List of constructed rate limit objects + **/ public setRateLimits(list: RateLimitConstructorList) { this.rateLimits = { normal: {}, @@ -432,6 +509,9 @@ export class Socket extends EventEmitter { } } + /** + * Reset this socket's rate limits to the defaults + **/ public resetRateLimits() { // TODO Permissions let isAdmin = false; @@ -452,6 +532,10 @@ export class Socket extends EventEmitter { } } + /** + * Set this socket's note quota + * @param params Note quota params object + **/ public setNoteQuota(params = NoteQuota.PARAMS_NORMAL) { this.noteQuota.setParams(params as any); // TODO why any @@ -466,6 +550,10 @@ export class Socket extends EventEmitter { ]); } + /** + * Make this socket play a note in the channel they are in + * @param msg Note message from client + **/ public playNotes(msg: ServerEvents["n"]) { const ch = this.getCurrentChannel(); if (!ch) return; @@ -474,6 +562,9 @@ export class Socket extends EventEmitter { private isSubscribedToChannelList = false; + /** + * Start sending this socket the list of channels periodically + **/ public subscribeToChannelList() { if (this.isSubscribedToChannelList) return; @@ -487,13 +578,21 @@ export class Socket extends EventEmitter { this.isSubscribedToChannelList = true; } + /** + * Stop sending this socket the list of channels periodically + **/ public unsubscribeFromChannelList() { if (!this.isSubscribedToChannelList) return; ChannelList.unsubscribe(this.id); this.isSubscribedToChannelList = false; } - public sendChannelList(list: IChannelInfo[], complete: boolean = true) { + /** + * Send a channel list to this socket + * @param list List of channels to send + * @param complete Whether this list is the complete list of channels or just a partial list + **/ + public sendChannelList(list: IChannelInfo[], complete = true) { // logger.debug( // "Sending channel list:", // list, @@ -509,6 +608,10 @@ export class Socket extends EventEmitter { ]); } + /** + * Determine if this socket has the crown in the channel they are in + * @returns Whether or not they have ownership in the channel + **/ public isOwner() { const channel = this.getCurrentChannel(); const part = this.getParticipant(); @@ -524,6 +627,12 @@ export class Socket extends EventEmitter { return true; } + /** + * Make this socket kick a user in their channel + * @param _id User ID to kick + * @param ms Amount of time in milliseconds to ban the user for + * @param admin Whether or not to force this change (skips checking channel ownership) + **/ public kickban(_id: string, ms: number, admin = false) { const channel = this.getCurrentChannel(); @@ -534,6 +643,11 @@ export class Socket extends EventEmitter { } } + /** + * Make this socket unban a user in their channel + * @param _id User ID to unban + * @param admin Whether or not to force this change (skips checking channel ownership) + **/ public unban(_id: string, admin = false) { const channel = this.getCurrentChannel(); @@ -544,10 +658,28 @@ export class Socket extends EventEmitter { } } + /** + * Get this socket's UUID + **/ public getUUID() { return this.uuid; } + /** + * Send this socket a notification message + * @param notif Notification data to send + * + * Example: + * ```ts + * socket.sendNotification({ + * title: "Notice", + * text: `Banned from "${this.getID()}" for ${Math.floor(t / 1000 / 60)} minutes.`, + * duration: 7000, + * target: "#room", + * class: "short" + * }); + * ``` + **/ public sendNotification(notif: Notification) { this.sendArray([{ m: "notification", @@ -561,6 +693,11 @@ export class Socket extends EventEmitter { }]); } + /** + * Set this socket's user's tag + * @param text Text of the tag + * @param color Color of the tag + **/ public setTag(text: string, color: string) { const user = this.getUser(); if (!user) return;