@eleven-am/pondsocket 0.1.55 → 0.1.57

package/src/endpoint/endpoint.ts

@@ -0,0 +1,304 @@
+import { WebSocket, WebSocketServer } from 'ws';
+
+import { Middleware } from '../abstracts/middleware';
+import { ChannelEngine } from '../channel/channel';
+import { ServerActions, SystemSender, ErrorTypes, ClientActions } from '../enums';
+import { EndpointError, PresenceError, ChannelError } from '../errors/pondError';
+import { JoinRequest } from '../lobby/joinRequest';
+import { JoinResponse } from '../lobby/joinResponse';
+import { LobbyEngine, PondChannel } from '../lobby/lobby';
+import { parseAddress } from '../matcher/matcher';
+// eslint-disable-next-line import/no-unresolved
+import { PondAssigns, ClientMessage, PondMessage, ChannelEvent, JoinParams, PondPath } from '../types';
+
+type AuthorizationHandler<Event extends string> = (request: JoinRequest<Event>, response: JoinResponse) => void | Promise<void>;
+
+export interface SocketCache {
+    clientId: string;
+    socket: WebSocket;
+    assigns: PondAssigns;
+}
+
+export interface RequestCache extends SocketCache {
+    channelName: string;
+}
+
+export class Endpoint {
+    readonly #middleware: Middleware<RequestCache, JoinParams>;
+
+    readonly #server: WebSocketServer;
+
+    readonly #channels: Set<LobbyEngine>;
+
+    readonly #sockets: Set<SocketCache>;
+
+    constructor (server: WebSocketServer) {
+        this.#server = server;
+        this.#sockets = new Set();
+        this.#middleware = new Middleware();
+        this.#channels = new Set();
+    }
+
+    /**
+     * @desc Adds a new PondChannel to this path on this endpoint
+     * @param path - The path to add the channel to
+     * @param handler - The handler to use to authenticate the client
+     *
+     * @example
+     * const channel = endpoint.createChannel('/chat', (request, response) => {
+     *     if (request.user.assigns.admin)
+     *         response.accept();
+     *
+     *     else
+     *         response.reject('You are not an admin', 403);
+     * });
+     */
+    public createChannel<Path extends string> (path: PondPath<Path>, handler: AuthorizationHandler<Path>) {
+        const pondChannel = new LobbyEngine();
+
+        this.#middleware.use((user, joinParams, next) => {
+            const event = parseAddress(path, user.channelName);
+
+            if (event) {
+                const newChannel = pondChannel.getChannel(user.channelName) || pondChannel.createChannel(user.channelName);
+                const request = new JoinRequest(user, joinParams, newChannel);
+                const response = new JoinResponse(user, newChannel);
+
+                if (request._parseQueries(path)) {
+                    return handler(request as JoinRequest<Path>, response);
+                }
+            }
+
+            next();
+        });
+
+        this.#channels.add(pondChannel);
+
+        return new PondChannel(pondChannel);
+    }
+
+    /**
+     * @desc List all clients connected to this endpoint
+     */
+    public listConnections () {
+        return [...this.#sockets].map(({ clientId }) => clientId);
+    }
+
+    /**
+     * @desc Gets all clients connected to this endpoint
+     */
+    public getClients () {
+        return [...this.#sockets];
+    }
+
+    /**
+     * @desc Broadcasts a message to all clients connected to this endpoint
+     * @param event - The event to broadcast
+     * @param payload - The payload to broadcast
+     */
+    public broadcast (event: string, payload: PondMessage) {
+        this.#sockets.forEach(({ socket }) => {
+            const message: ChannelEvent = {
+                event,
+                payload,
+                action: ServerActions.BROADCAST,
+                channelName: SystemSender.ENDPOINT,
+            };
+
+            this.#sendMessage(socket, message);
+        });
+    }
+
+    /**
+     * @desc Closes specific clients connected to this endpoint
+     * @param clientIds - The id for the client / clients to close
+     */
+    public closeConnection (clientIds: string | string[]) {
+        const clients = typeof clientIds === 'string' ? [clientIds] : clientIds;
+
+        this.getClients()
+            .forEach(({ clientId, socket }) => {
+                if (clients.includes(clientId)) {
+                    socket.close();
+                }
+            });
+    }
+
+    /**
+     * @desc Manages a new socket connection
+     * @param cache - The socket cache
+     */
+    public manageSocket (cache: SocketCache) {
+        this.#sockets.add(cache);
+        const socket = cache.socket;
+
+        socket.addEventListener('message', (message) => {
+            this.#readMessage(cache, message.data as string);
+        });
+
+        socket.addEventListener('close', () => {
+            this.#channels
+                .forEach((manager) => manager.removeUser(cache.clientId, true));
+        });
+
+        socket.addEventListener('error', () => {
+            this.#channels
+                .forEach((manager) => manager.removeUser(cache.clientId, true));
+        });
+    }
+
+    /**
+     * @desc Sends a message to a client
+     * @param socket - The socket to send the message to
+     * @param message - The message to send
+     */
+    #sendMessage (socket: WebSocket, message: ChannelEvent) {
+        socket.send(JSON.stringify(message));
+    }
+
+    /**
+     * @desc Adds a new client to a channel on this endpoint
+     * @param channel - The channel to add the client to
+     * @param socket - The client to add to the channel
+     * @param joinParams - The parameters to pass to the channel
+     * @private
+     */
+    #joinChannel (channel: string, socket: SocketCache, joinParams: Record<string, any>) {
+        const cache: RequestCache = {
+            ...socket,
+            channelName: channel,
+        };
+
+        this.#middleware.run(cache, joinParams, () => {
+            throw new EndpointError(`GatewayEngine: Channel ${channel} does not exist`, 404);
+        });
+    }
+
+    /**
+     * @desc Executes a function on a channel
+     * @param channel - The channel to execute the function on
+     * @param handler - The function to execute
+     * @private
+     */
+    #execute<ReturnType> (channel: string, handler: ((manager: ChannelEngine) => ReturnType)): ReturnType {
+        for (const manager of this.#channels) {
+            const isPresent = manager.listChannels()
+                .includes(channel);
+
+            if (isPresent) {
+                return manager.execute(channel, handler);
+            }
+        }
+
+        throw new Error(`GatewayEngine: Channel ${channel} does not exist`);
+    }
+
+    /**
+     * @desc Deals with a message sent from a client
+     * @param cache - The socket cache of the client
+     * @param message - The message to handle
+     */
+    #handleMessage (cache: SocketCache, message: ClientMessage) {
+        switch (message.action) {
+            case ClientActions.JOIN_CHANNEL:
+                this.#joinChannel(message.channelName, cache, message.payload);
+                break;
+
+            case ClientActions.LEAVE_CHANNEL:
+                this.#execute(message.channelName, (channel) => {
+                    channel.removeUser(cache.clientId);
+                });
+                break;
+
+            case ClientActions.BROADCAST:
+                this.#execute(message.channelName, (channel) => {
+                    channel.broadcastMessage(cache.clientId, message);
+                });
+                break;
+            default:
+                throw new Error(`GatewayEngine: Action ${message.action} does not exist`);
+        }
+    }
+
+    /**
+     * @desc Handles a message sent from a client
+     * @param cache - The socket cache of the client
+     * @param message - The message to handle
+     * @private
+     */
+    #readMessage (cache: SocketCache, message: string) {
+        const errorMessage: ChannelEvent = {
+            event: ErrorTypes.INVALID_MESSAGE,
+            action: ServerActions.ERROR,
+            channelName: SystemSender.ENDPOINT,
+            payload: {},
+        };
+
+        try {
+            const data = JSON.parse(message) as ClientMessage;
+
+            if (!data.action) {
+                errorMessage.payload = {
+                    message: 'No action provided',
+                };
+            } else if (!data.channelName) {
+                errorMessage.payload = {
+                    message: 'No channel name provided',
+                };
+            } else if (!data.payload) {
+                errorMessage.payload = {
+                    message: 'No payload provided',
+                };
+            }
+
+            if (!this.#isObjectEmpty(errorMessage.payload)) {
+                this.#sendMessage(cache.socket, errorMessage);
+            } else {
+                this.#handleMessage(cache, data);
+            }
+        } catch (e) {
+            if (e instanceof SyntaxError) {
+                errorMessage.payload = {
+                    message: 'Invalid JSON',
+                };
+            } else if (e instanceof Error) {
+                errorMessage.event = ErrorTypes.INTERNAL_SERVER_ERROR;
+                errorMessage.payload = {
+                    message: e.message,
+                };
+            } else if (e instanceof PresenceError) {
+                errorMessage.event = ErrorTypes.PRESENCE_ERROR;
+                errorMessage.channelName = e.channel;
+                errorMessage.payload = {
+                    message: e.message,
+                    code: e.code,
+                    action: e.event,
+                };
+            } else if (e instanceof ChannelError) {
+                errorMessage.event = ErrorTypes.CHANNEL_ERROR;
+                errorMessage.channelName = e.channel;
+                errorMessage.payload = {
+                    message: e.message,
+                    code: e.code,
+                };
+            } else if (e instanceof EndpointError) {
+                errorMessage.event = ErrorTypes.ENDPOINT_ERROR;
+                errorMessage.payload = {
+                    message: e.message,
+                    code: e.code,
+                };
+            }
+
+            this.#sendMessage(cache.socket, errorMessage);
+        }
+    }
+
+    /**
+     * @desc Checks if an object is empty
+     * @param obj - The object to check
+     * @private
+     */
+    #isObjectEmpty (obj: Record<string, any>) {
+        return Object.keys(obj).length === 0;
+    }
+}

package/src/endpoint/response.ts

@@ -0,0 +1,106 @@
+import { WebSocket } from 'ws';
+
+import { Endpoint, SocketCache } from './endpoint';
+import { PondResponse } from '../abstracts/abstractResponse';
+import { ServerActions, ErrorTypes, SystemSender } from '../enums';
+import { EndpointError } from '../errors/pondError';
+// eslint-disable-next-line import/no-unresolved
+import { PondAssigns, PondMessage } from '../types';
+
+export class ConnectionResponse extends PondResponse {
+    readonly #webSocket: WebSocket;
+
+    readonly #engine: Endpoint;
+
+    readonly #clientId: string;
+
+    #executed: boolean;
+
+    constructor (webSocket: WebSocket, engine: Endpoint, clientId: string) {
+        super();
+        this.#webSocket = webSocket;
+        this.#engine = engine;
+        this.#clientId = clientId;
+        this.#executed = false;
+    }
+
+    /**
+     * @desc Accepts the request and optionally assigns data to the client
+     * @param assigns - the data to assign to the client
+     */
+    public accept (assigns?: PondAssigns) {
+        this.#performChecks();
+        const cache: SocketCache = {
+            clientId: this.#clientId,
+            socket: this.#webSocket,
+            assigns: assigns || {},
+        };
+
+        this.#engine.manageSocket(cache);
+    }
+
+    /**
+     * @desc Rejects the request with the given error message
+     * @param message - the error message
+     * @param errorCode - the error code
+     */
+    public reject (message?: string, errorCode?: number) {
+        this.#performChecks();
+        const payload = {
+            message: message || 'Unauthorized connection',
+            code: errorCode || 401,
+        };
+
+        this.#sendMessage(
+            ServerActions.ERROR,
+            ErrorTypes.UNAUTHORIZED_CONNECTION,
+            payload,
+        );
+
+        this.#webSocket.close();
+    }
+
+    /**
+     * @desc Emits a direct message to the client
+     * @param event - the event name
+     * @param payload - the payload to send
+     * @param assigns - the data to assign to the client
+     */
+    public send (event: string, payload: PondMessage, assigns?: PondAssigns) {
+        this.accept(assigns);
+        this.#sendMessage(ServerActions.BROADCAST, event, payload);
+    }
+
+    /**
+     * @desc Emits a direct message to the client
+     * @param action - the action to perform
+     * @param event - the event name
+     * @param payload - the payload to send
+     * @private
+     */
+    #sendMessage (action: ServerActions, event: string, payload: PondMessage) {
+        const message = {
+            action,
+            event,
+            payload,
+            channelName: SystemSender.ENDPOINT,
+        };
+
+        this.#webSocket.send(JSON.stringify(message));
+    }
+
+    /**
+     * @desc Performs checks to ensure the response has not been executed
+     * @private
+     */
+    #performChecks (): void {
+        if (this.#executed) {
+            const message = 'Cannot execute response more than once';
+            const code = 403;
+
+            throw new EndpointError(message, code);
+        }
+
+        this.#executed = true;
+    }
+}

package/src/enums.ts

@@ -0,0 +1,52 @@
+export enum PresenceEventTypes {
+    JOIN = 'JOIN',
+    LEAVE = 'LEAVE',
+    UPDATE = 'UPDATE'
+}
+
+export enum ServerActions {
+    PRESENCE = 'PRESENCE',
+    SYSTEM = 'SYSTEM',
+    BROADCAST = 'BROADCAST',
+    ERROR = 'ERROR',
+}
+
+export enum ClientActions {
+    JOIN_CHANNEL = 'JOIN_CHANNEL',
+    LEAVE_CHANNEL = 'LEAVE_CHANNEL',
+    BROADCAST = 'BROADCAST',
+}
+
+export enum ChannelState {
+    IDLE = 'IDLE',
+    JOINING = 'JOINING',
+    JOINED = 'JOINED',
+    STALLED = 'STALLED',
+    CLOSED = 'CLOSED',
+}
+
+export enum ErrorTypes {
+    UNAUTHORIZED_CONNECTION = 'UNAUTHORIZED_CONNECTION',
+    UNAUTHORIZED_JOIN_REQUEST = 'UNAUTHORIZED_JOIN_REQUEST',
+    UNAUTHORIZED_BROADCAST = 'UNAUTHORIZED_BROADCAST',
+    INVALID_MESSAGE = 'INVALID_MESSAGE',
+    HANDLER_NOT_FOUND = 'HANDLER_NOT_FOUND',
+    PRESENCE_ERROR = 'PRESENCE_ERROR',
+    CHANNEL_ERROR = 'CHANNEL_ERROR',
+    ENDPOINT_ERROR = 'ENDPOINT_ERROR',
+    INTERNAL_SERVER_ERROR = 'INTERNAL_SERVER_ERROR',
+}
+
+export enum SystemSender {
+    ENDPOINT = 'ENDPOINT',
+    CHANNEL = 'CHANNEL',
+}
+
+export enum ChannelReceiver {
+    ALL_USERS = 'ALL_USERS',
+    ALL_EXCEPT_SENDER = 'ALL_EXCEPT_SENDER',
+}
+
+export enum Events {
+    ACKNOWLEDGE = 'ACKNOWLEDGE',
+}

package/src/errors/pondError.ts

@@ -0,0 +1,32 @@
+import { PresenceEventTypes } from '../enums';
+
+export class PondError {
+    public message: string;
+
+    public code: number;
+
+    constructor (message: string, code: number) {
+        this.code = code;
+        this.message = message;
+    }
+}
+
+export class EndpointError extends PondError {}
+
+export class ChannelError extends EndpointError {
+    public channel: string;
+
+    constructor (message: string, code: number, channel: string) {
+        super(message, code);
+        this.channel = channel;
+    }
+}
+
+export class PresenceError extends ChannelError {
+    public event: PresenceEventTypes;
+
+    constructor (message: string, code: number, channel: string, event: PresenceEventTypes) {
+        super(message, code, channel);
+        this.event = event;
+    }
+}

package/src/express.ts

@@ -0,0 +1,58 @@
+import { createServer } from 'http';
+
+// eslint-disable-next-line import/no-unresolved
+import { Express } from 'express';
+
+import { Endpoint } from './endpoint/endpoint';
+import { ConnectionResponse } from './endpoint/response';
+import { PondSocket } from './server/pondSocket';
+// eslint-disable-next-line import/no-unresolved
+import { PondPath, IncomingConnection } from './types';
+
+declare global {
+    // eslint-disable-next-line @typescript-eslint/no-namespace
+    namespace Express {
+        export interface Application {
+            upgrade<Path extends string>(path: PondPath<Path>, handler: (request: IncomingConnection<Path>, response: ConnectionResponse) => void | Promise<void>): Endpoint;
+        }
+    }
+}
+
+
+interface PondSocketExpressApp extends Express {
+
+    /**
+     * @desc Accepts a new socket upgrade request on the provided endpoint using the handler function to authenticate the socket
+     * @param path - the pattern to accept || can also be a regex
+     * @param handler - the handler function to authenticate the socket
+     * @example
+     * const endpoint = pond.createEndpoint('/api/socket', (req, res) => {
+     *    const token = req.query.token;
+     *    if (!token)
+     *       return res.reject("No token provided");
+     *    res.accept({
+     *       assign: {
+     *           token
+     *       }
+     *    });
+     * })
+     */
+    upgrade<Path extends string>(path: PondPath<Path>, handler: (request: IncomingConnection<Path>, response: ConnectionResponse) => void | Promise<void>): Endpoint;
+}
+
+/**
+ * @desc Creates a pond socket server
+ * @param app - The Express app to be used by the server
+ * @constructor
+ */
+const pondSocket = (app: Express): PondSocketExpressApp => {
+    const server = createServer(app);
+    const pondSocket = new PondSocket(server);
+
+    app.upgrade = (path, handler) => pondSocket.createEndpoint(path, handler);
+    app.listen = (...args: any[]) => pondSocket.listen(...args);
+
+    return app as PondSocketExpressApp;
+};
+
+export default pondSocket;

package/src/index.ts

@@ -0,0 +1,3 @@
+import { PondSocket } from './server/pondSocket';
+
+export default PondSocket;

package/src/lobby/JoinRequest.test.ts

@@ -0,0 +1,48 @@
+import { JoinRequest } from './joinRequest';
+import { createChannelEngine } from '../channel/eventResponse.test';
+import { RequestCache } from '../endpoint/endpoint';
+
+const createMockSocket = (params = {}) => {
+    const channelEngine = createChannelEngine();
+
+    const socket: RequestCache = {
+        clientId: 'sender',
+        assigns: { assign: 'assign' },
+        channelName: 'channel',
+        socket: {
+            send: jest.fn(),
+        } as any,
+    };
+
+    const request = new JoinRequest(socket, params, channelEngine);
+
+    return {
+        channelEngine,
+        socket,
+        request,
+    };
+};
+
+describe('JoinRequest', () => {
+    it('should create a new PondChannelResponse', () => {
+        const { request } = createMockSocket();
+
+        expect(request).toBeDefined();
+    });
+
+    it('should return the join params', () => {
+        const { request } = createMockSocket({ params: 'params' });
+
+        expect(request.joinParams).toEqual({ params: 'params' });
+    });
+
+    it('should return the user data', () => {
+        const { request } = createMockSocket();
+
+        expect(request.user).toEqual({
+            id: 'sender',
+            assigns: { assign: 'assign' },
+            presence: {},
+        });
+    });
+});