socketIO.js

/* 
 * API to configure Web Sockets, and handle socket write and read events 
 * generated by websocktes. The API is designed to work in conjunction with a 
 * TCP server that creates websockets from HTTP connections used for duplexed
 * communication from server to client and vice versa.
 * 
 * Date: 9/6/2019
 * Version: 1.0
 * 
 * TODO: 
 * 1. Test multi-frame, fragmented message implementation
 * 
 * 2. Test max payload length message frame. Are the correct numbers being used?
 * 
 * 3. Should the socket tracked by this script hold a reference to the handlers
 *    used to process new connection requests and when data is recieved by the 
 *    server that uses the socket connection to communicate with the client?
 *    
 * 4. Should a socket be configured with an id number?
 */

// Import modules
const net = require('net');
const crypto = require('crypto'); 
const MAX_NUMBER_USERS = 100;

/* Method to handle the setup for a web socket that is created by this server 
 * when a connection is made by a client. The method will set all the purtenet
 * properties for a socket that is managed by this API.*/
exports.configureSocket = function (socket, onConnected, onDataRecieved, onClose)
{
    /* Give the socket an id so that it can be associated with other data while
     * its connected. Generate a random number between 0 and 100. Maybe find a 
     * way to ensure these are unique. */
    socket.ID = Math.round((Math.random() * MAX_NUMBER_USERS)); 
    
    /* Add a user name property to the socket so that the socekt can be identified
     * by user name if desired*/
    socket.ownerName = "";
    
    /* Add payload String property to the socket so that it can hold multiple 
     * frame's worth of messages until the final frame is recieved and proccessed*/
    socket.payloadString = "";
    
    /* Add a message opcode to the socket object so that the socket can keep 
     * track of a fragmented message's opcode.*/
    socket.opcode = 0; 
    
    // Add a isConnected boolean flag property to the socket
    socket.isConnected = false; 
        
    // Tell the console the connection was made by a socket which is a client DEBUG
    console.log("CONNECTED: " + socket.remoteAddress + ":" + socket.remotePort +
                " socket ID: " + socket.ID);
    
    // Listen for data events. Fired when data is recieved on the socket line.
    socket.on("data", function (data)
    {
        /* See if this socket is already connected between this server and the 
         * client */
        if (!socket.isConnected)
        { 
            // If this is a new connection attempt to establish it. 
            establishClientConnection(socket, data.toString(), onConnected);           
        }
        else 
        {
            /* If the connection was already established then process the string
             * data in the payload. */
            processPayload(socket, data, onDataRecieved);
        }        
    });
    
    // Add a socket communication error listener to track when errors are emitted
    socket.on("error", function (error)
    {
        // Log these error to a file 
        console.log("Server Level error: " + error.message);
    });
    
    // Add Close listener for the socket to handle closing events 
    socket.on("close", function ()
    {
        // Call the close handler function
        onClose(socket);
    });
    
    return socket;
};

/* Method to send data back to the client on a given socket. The data will be 
 * framed correctly before being sent.*/
exports.send = function (socket, data)
{
//    console.log("Frame length: " + data.length);
//    console.log("The Frame: " + exports.frameData(data).toString());
//    console.log("The Frame: " + JSON.stringify(exports.frameData(data)));
    
    socket.write(frameData(data));
};

/* Method to process and extract the payload from an incoming frame sent to this 
 * server. The payload will be converted to either a string or left as binary 
 * data after its extraction. The method is event driven and will fire a callback
 * function when all the frame for the entire message has been recieved and 
 * parsed.*/
function processPayload(socket, fBytes, handleText = undefined, handleBinary = undefined)
{
    /* Attempt to parse the frame getting the frame's payload and then processing
     * that data from there */
    try 
    {
        processFrameData(socket, fBytes, handleText, handleBinary);
    }
    catch (error)
    {
        // Close the socket connection 
        socket.destroy({message: "Incoming Frame Proccessing Error: " + 
                                  error.message});
    }
}

/* Method to parse the elements of the socket frame. The method will and object 
 * that will contain all the aspects of the frame as key-value pairs. The method
 * will not decrypt the pay load but will return the buffer index offset so that
 * the caller knows where in the buffer to start to begin the decryption process.*/
function processFrameData(socket, data, handleTxtPayload = null, handleBiPayload = null)
{
    // Local Variable Declaration
    let payloadLength = 0, dataDex = 0, aByte = 0, maskKeys = [0], fin = 0, 
        rsv1 = 0, rsv2 = 0, rsv3 = 0, mask = 0, opCode = 0;         
    const FIN_FLAG = 128, RSV_1_FLAG = 64, RSV_2_FLAG = 32, RSV_3_FLAG = 16, 
          OPCODE_FLAG = 15, MASK_FLAG = 128, PYLD_LENGTH_FLAG = 127, 
          MAX_PYLD_LENGTH = 9223372036854775808; 

    // Get the first byte, store it as base 10
    aByte = data[dataDex];
    
    // Use a flag to determine wheather the fin bit was set
    fin = aByte & FIN_FLAG ? true : false;
    
    // Use flags to determine which reserve bits were set
    rsv1 = aByte & RSV_1_FLAG ? true : false;
    rsv2 = aByte & RSV_2_FLAG ? true : false;
    rsv3 = aByte & RSV_3_FLAG ? true : false;
    
    // Use a flag to determine the opcode
    opCode = aByte & OPCODE_FLAG;
    
    // Get the second byte from the buffer and store it as base 10
    aByte = data[++dataDex];
    
    // Determine whether the mask bit was set using a flag
    mask = aByte & MASK_FLAG ? true : false;
    
    // Make sure the incoming message was masked
    if (!mask)
    {
        // If the frame was not masked throw an error
        throw new Error ("All incoming frames from a client must be masked");
    }
    
    // Determine the payload length using a payload length flag, store it as base 10
    payloadLength = aByte & PYLD_LENGTH_FLAG;
    
    // Determine how many bytes the payload length figure takes up in the frame
    if (payloadLength === 126)
    {
        // Local Variable Declaration 
        let total = 255; 
        
        /* If the payload length is 126 then the payload length is contained in
         * the next 16 bits. Get the first byte's (high byte) worth of the 
         * number, and save it into the total number*/
        total &= data[++dataDex];
        
        // Shift the total up by eight bits. Zeros will be shifted in from right
        total <<= 8; 
        
        /* Concatenate the the second byte (low byte) with the total using a 
         * bitwise XOR */
        total ^= data[++dataDex];
        
        // Store the payloadLength
        payloadLength = total;
    }
    else if (payloadLength === 127)
    {
        // Local Variable Declaration 
         let total = 0;
         const highBitFlag = -9223372036854775808;
        
        /* If the payload length was 127 or if the paylength was 126 but the 
         * result of parsing the next 16 bits was 127 then the payload length 
         * really was contained in the next 64 bits. Loop 8 times to create a 
         * number out of all the bytes designated in the frame*/
        for (let i = 0; i < 8; i++)
        {
            // Concatinate the next byte in
             total ^= data[++dataDex];
             
             // Shift the byte over to make room for the next 
             total <<= 8; 
        }
        
        // Check to see if the number contained 0 for the most significant bit.
        payloadLength = total & highBitFlag ? -1 : total; 
    }
    // Make sure the 
    if (payloadLength < 0 || payloadLength > MAX_PYLD_LENGTH)
    {
        /* There was an error with the frame the payload length is outside of 
         * acceptable parameters */
        throw new Error ("Payload length is out of bounds: " + payloadLength);
    }
    
    // Finally get the masking key from the next 32 bits (loop through the buffer)
    for (let i = 0; i < 4; i++)
    {
        // Put the byte from the buffer into the maskKey array
        maskKeys[i] = data[++dataDex];
    }
    
    /* Decrypt and store the message character by character (byte by byte)
     * from the the rest fo the data buffer using the key from the message frame.
     * Add the message data bytes to the payload string for the socket connection
     * this will in effect concatenate this frame's data to the prior frame's 
     * data. */
    for (let i = 0; i < payloadLength; i++)
    {
        /* Unmask the payload by using the mask key bytes. These bytes came from 
         * the frame and when XORed with the masked bytes from the payload of the
         * frame the data is decrypted. Each byte in the payload is paired with
         * the (i mod maskBytes.length)th mask byte.*/
        socket.payloadString += String.fromCharCode(data[++dataDex] ^ maskKeys[i % maskKeys.length]);
    }
    
    // Process the data according to the frame's opcode and fin bit
    if (fin)
    {
        /* If the fin bit is set (1) then the message is complete, this was the 
         * last frame. Continue processing according to the opcode */
        if (opCode === 0)
        {                       
            // Get the opcode from the message's first frame 
            opCode = socket.opcode; 
        }
        
        /* Check the message's first frame's opcode to see what to do with the 
         * final message */
        if (opCode === 1)
        {
            /* Fire call back function that will process the parsed data's message
             * if one was passed. This method only called when all fragments 
             * have been parsed */
            if (handleTxtPayload !== null)
            {
                handleTxtPayload(socket, socket.payloadString);   
            }
            
            // Clear payload data
            socket.payloadString = "";
        }
        else if (opCode === 2)
        {
            /* Fire callback function that will process binary data if one was 
             * passed */
            if (handleBiPayload !== null)
            {
                handleBiPayload (socket, socket.payloadString);
            }
            
            // Clear payload data
            socket.payloadString = "";
        }
        else if (opCode === 8)
        {
            // The client wants to close the socket connection
            
            // Log the reason
            let reason = socket.payloadString; 
            console.log("The reason is: " + reason);
            
            // Echo the the close frame back 
            socket.write(frameData(reason));
            
            // Close the connection 
            socket.destroy();            
        }
        else if (opCode === 9)
        {
            // Handle Ping by sending the data from that ping back as a pong
            socket.write(frameData(socket.payloadString));
        }
        else if (opCode === 10)
        {
            // Handle Pong
        }
    }
    else 
    {
        /* If the fin bit is not set (0) then the message is not finished coming
         * in. Start by checking what the opcode is and save it on the socket if
         * not zero. In effect acknoweldge all zero opcodes, but don't save them.*/
         socket.opcode = opCode > 0 ? opCode : socket.opcode;    
    }
}

/* Method to send multiple data message fragments in different frames down the 
 * socket to a client. The method is expecting an array of data message 
 * fragments and the socket, which to write the message. */
function writeDataFragments(socket, fragments)
{
    // Local Variable Declaration 
    let aFrame;
    
    // Loop through the data fragments 
    for (let i = 0; i < fragments.length; i++)
    {
        // Call frameData for the data fragment 
        aFrame = frameData(fragments[i]);
        
        // Write that frame (data fragment) to the socket
        socket.write(aFrame);
    }
}

/* Method to write a text message back to client through a socket connection. 
 * Fix it to work with multiple frames.*/
function frameData(data, isLastFrame = true)
{
    // Local Variable Declaration
    let replyBuffer;
    let buffDex = 0, payloadByteLength = 0, dataLength = data.length, 
        payloadLengthCode = 0, dataByte = 0; 
    
    /* Find out the bit length of the data to send back to the client. Start 
     * with the max length for a payload which is 64 bits wide*/
    if (dataLength < Math.pow(2,63) && dataLength > Math.pow(2, 16))
    {
        // Set the payload length to 127 and the mask bit to 0
        payloadLengthCode = 127;

        // The payLoad length will take up 8 bytes
        payloadByteLength = 8;
    }
    else if(dataLength < Math.pow(2,16) && dataLength > 125)
    {
        // Set the mask bit to 0 and add the payload length 
        payloadLengthCode = 126;
        
        // The payload length with take up the next two bytes
        payloadByteLength = 2;
    }
    else if(dataLength <= 125 && dataLength >= 0)
    {
        /* Set the mask to 0 and the payload length to the length of 
         * the data response */
        payloadLengthCode = dataLength;
        
        /* The payload byte length will be zero, because the message length is 
         * the payload length */
        payloadByteLength = 0;
    }
    else 
    {
        // We have a payload size error. Not sure what to do here
        
    }
    
    // Allocate a buffer for the message data
    replyBuffer = Buffer.alloc(2 + payloadByteLength + dataLength);
    
    /* Set the first byte sequence which includes the FIN bit and opcode. If this
     * frame is the first in a multi frame message then the FIN bit should be 0 
     * and the opcode should be 1 (for text). If its the last frame then the FIN
     * bit should be 1 and the opcode should be 0.*/
    replyBuffer[buffDex] = isLastFrame ? 129 : 1;
    
    // Set the second byte with the mask bit 0 and the payload length code
    replyBuffer[++buffDex] = payloadLengthCode;
    
    /* The next set of bytes to add to the buffer are the bytes that comprise 
     * payload length. The payload length number could be 1 byte, 2 bytes, or 8
     * bytes wide and needs to put in the correct order with low byte of the 
     * payload length number put in the low byte position (last byte) in the 
     * frame payload length position. Therefore, set the position of the buffer 
     * index to the position where the low byte of the payload length should go
     * unless the payload length is 0 meaning the payload length was less than 
     * 125. */
    buffDex += (payloadByteLength > 0) ? (payloadByteLength) : 0;
    
    /* For the amount of bytes in the payload loop through and add each byte of
     * the payload length starting at the position of the last byte*/
    for (let i = 0; i < payloadByteLength; i++)
    {
        // Capture the payload length as a bit string
        replyBuffer[buffDex - i] = dataLength & 255;
        
        // Shift the least significant 8 bits off the end of messageLength
        dataLength >>>= 8; 
    }
    
    // Loop through each byte of data and add it to the return frame
    for (let i = 0; i < data.length; i++)
    {
        // Add message to frame, transforming it char by char to bytes
        replyBuffer[++buffDex] = data.charCodeAt(i);   
    }
    
    return replyBuffer;
};

/* Method to respond to a HTTP GET request for a new connection to this server.
 * The method will parse the HTTP request headers, validate them, and then 
 * complete the handshake between this server and the client over the headers
 * (terms) of this connection request. Note once the connection headers are 
 * validated the connection callback method will be fired. The handshake header
 * will be sent after the callback function has been fired. */
async function establishClientConnection(socket, hBytes, onConnected = undefined)
{
    // Local Variable Declaration 
    let theHeader = {};
    let validatedRequest = "";

    // Parse the header
    theHeader = parseConnectionRequestHeader(hBytes);   

    // Validate connection request header
    validatedRequest = validateRequestHeader(theHeader); 

    // See if the request header was valid
    if (validatedRequest === "")
    {
         // Set a connection flag for the socket just connected 
         socket.isConnected = true;
         
         /* Add the owner name of the socket, which was passed in the URL when
          * the connection was requested*/
         socket.ownerName = theHeader.URL.slice(1); 
         
         /* Once a connection has been made successfully fire a call back 
          * function if it was passed. Assume any callback function passed should
          * be preformed asyncrounsouly. */
         if (onConnected !== undefined)
         {
             await onConnected(socket);
         }
         
        /* Finally, complete the handshake by sending a connection changing 
         * response header back to the client. */
         sendConnectHeader(theHeader["Sec-WebSocket-Key"], socket);
    }
    else 
    {
        /* If the request was invalid send a Bad Request header back to
         * the client */
        sendBadRequestHeader(validatedRequest, socket);

        // Disconnect from client 
        socket.destroy({message: "The connection request was malformed"});
    }
}

/* Method to parse header data recieved from the client attempting to connect
 * to this server.*/
function parseConnectionRequestHeader(hData)
{  
    // Local Variable Declaration 
    let hLines = [""];
    let lineTokens = [];
    let i = 0;
    let headers = {};
    
    // Find the outter bound index of the first line of the request header
    hLines = hData.trim().split("\r\n");
    
    // Tokenize the first line over the space character 
    lineTokens = hLines[0].split(" ");
    
    // Set the request method from the first line
    headers["Method"] = lineTokens[0]; 
    
    // Set the URL from the first line of the connection request header
    headers["URL"] = lineTokens[1];
    
    // Set protocol of the request
    headers["Protocol-Version"] = lineTokens[2];
    
    /* Run through the rest of the connection request header and parse the data 
     * into the headerObj*/
    for (i = 1; i < hLines.length; i++)
    {
        // Parse each line over the colon operator
        lineTokens = hLines[i].split(": ");
        
        // Put the keys and values in the object
        headers[lineTokens[0]] = lineTokens[1];
    }
    
    return headers;
};

/* Method to validate the request header. The method seeks to make sure all the 
 * essential headers were sent from the client when they requested the websocket
 * connection */
function validateRequestHeader(headers)
{
    // Local Variable Declaration 
    let isValid = ""; 
    
    // Check to make sure the method used was GET 
    isValid += (headers.Method === "GET")? "" : "Method: GET";
    
    // Checkt the HTTP version it needs to be at least 1.1
    isValid += (headers['Protocol-Version'] === "HTTP/1.1") ? "" : "Protocol-Version: HTTP/1.1\r\n";
    
    // Check the Upgrade header 
    isValid += headers.Upgrade === "websocket" ? "" : "Upgrade: websocket\r\n";
    
    // Check the Connection header 
    isValid += headers.Connection === "Upgrade" ? "" : "Connection: Upgrade\r\n";
    
    // Check the Socket version header it needs to be at leaset 13
    isValid += headers['Sec-WebSocket-Version'] === "13" ? "" : "Sec-WebSocket-Version: 13\r\n";
    
    // Make sure the header has WebSocket Key header 
    isValid += headers.hasOwnProperty('Sec-WebSocket-Key') ? "" : "Sec-WebSocket-Key is missing\r\n";
    
    // Check Origin
    
    // Check protocol
    
    // Check extension
    
    return isValid;
}

/* Method to complete the connection handshake with the client. The method will
 * compute the hash code to send back to the client, and then send the headers 
 * back.*/
function sendConnectHeader(reqKey, socket)
{
   // Local Variable Declaration 
   let acceptKey = "",
       magicString = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11",
       resHeader = "";
       
   // Create a hash object to process and create a hashcode to send to the client
   const hash = crypto.createHash("sha1");
   
   // Concatenate the "magic string" with the client key, and load the hash object with the result
    hash.update((reqKey + magicString));
    
    // Hash the key and get the result
    acceptKey = hash.digest("base64");
   
    // Create a header to send back to the client
    resHeader = "HTTP/1.1 101 Switching Protocols\r\n" +
                "Upgrade: websocket\r\n" +
                "Connection: Upgrade\r\n" +
                "Sec-WebSocket-Accept: " + acceptKey + "\r\n\r\n";
      
    // Send the header back to the client
    socket.write(resHeader, "utf8");
}

/* Method to send a message to the client that the request was invalid. The 
 * method will list the incorrect headers in the response header sent back to 
 * the client. */
function sendBadRequestHeader (badHeaders, socket)
{
    // Local Variable Declaration 
    let resHeader = "";
    let headers = [];
    
    // Parse headers 
    headers = badHeaders.split("\r\n");
    
    // Create the response header
    resHeader = "HTTP/1.1 400 Bad Request\r\n";
    
    // Loop through all the bad headers to create a response header string
    for (const aHeader in headers)
    {
        // Concatinate the response headers 
        resHeader += headers + "\r\n";
    }
    
    // Add the final CRLF to the header
    resHeader += "\r\n";
    
    // Send the header back to the client
    socket.write(resHeader, "utf8");
}