Build a WebSocket server with Node.js - no libraries - 2026

To establish a WebSocket connection, it is essential to have an existing HTTP server that is already established and running. This requirement applies to all versions of HTTP, including HTTP/1.1, HTTP/2, and HTTP/3.

Many developers think once you create a websocket server, your http server falls away. But this could not be further from the truth.

I have attached the starting HTML and CSS files to this lecture.

I have added some extra comments to make more sense of it.

This is the starting file for the client-side code.

In this index.html file, we set up the form and buttons that allow a user to open up a WS connection, submit data, and also close a WebSocket connection.

As you will recall (from doing my WebSockets fundamentals course) you'll know that there are 4 events on the WebSocket API and 2 methods.

I will attach the HTML and CSS starting files to the next lecture so you can download the starting client-side code.

We will now use Node's inbuilt native 'http' module to create a HTTP server. This will form the entry point for our WebSocket server.

We will define our PORT variable (and a bunch of others throughout this course) in a separate module. This makes for cleaner and better code.

In this lecture I want to add a CUSTOM_ERRORS error to our modules folder, and then use JavaScript's forEach loop to add each custom error event to our process object in node.

Visual Studio Code (VSCode) provides built-in support for running and debugging Node.js applications, including servers and WebSocket APIs.

Before I end this section, I want to test that our error handling code is working as expected. You'll learn that the SIGINT is not really an "error" in the true strict sense of the word, and I'll show you that our custom event handler function does indeed work.

I'll finally also explain a little more about what process.exit() is and why I passed an exit code of "1" into the function.

I have attached the final code for this section.

When a client wishes to establish a WebSocket connection, it initiates the process by sending an HTTP request to the server. This request includes specific headers that indicate the client's intent to upgrade the connection to WebSocket.

Whenever an 'upgrade' event is fired, Node.js will fire the 'upgrade' event listener and in doing so will provide us with 3 important objects:

1. the request object,

2. the socket object

3. the head buffer

As you'll see, when a request is received from the client, it is of type IncomingMessage. If we examine this object in Node's terminal, you'll notice that there is a rawHeaders property but not a plain "headers" property. I will explain why this is the case in this lecture.

In this lecture we will look at the req.headers object to examine and perform checks on the client's upgrade request. It needs to be in conformance with the RFC 6455, which means we will have to define some custom error handling.

Rather than kill our server if there is an error in the client handshake headers, let's make sure our code is in compliance with the RFC by sending back an appropriate HTTP/1.1 response.

In this lecture we will start to generate the required headers that the server needs to send back to the client in order to accept a valid WebSocket protocol request.

As you know, one required header that the server needs to respond back with is the Sec-WebSocket-Accept header. The value of this header is a 3 step-process. The first step is to concatenate (fancy dev word for "join") the client Sec-WebSocket-Key with the GUID. In this lecture I want to set up functions to handle this.

In order to calculate the Sec-WebSocket-Accept value, we are required by the WebSocket protocol to perform a SHA1 hash and encode it using base64.

I want to finish generating the Sec-WebSocket-Accept value in this lecture, and send back the appropriate headers to the client. If everything was done successfully at this point, we have a valid WebSocket connection.

In this lecture we will end part 1 of this course - that is, writing native code that establishes a WebSocket connection with a client.

Remember, even though we have a valid WebSocket connection, we have not written any server-code that can handle messages. This is a topic we will cover the remainder of the course.

I can't wait.

Here is a summary of the upgrade process.

Here is the final project code up to this point.

Running a WebSocket connection over HTTPS and TLS is useful for developing web applications that require secure connections, such as those using service workers or APIs that enforce HTTPS.

So, let's do it!

Our project is a little complex in the sense that we are running 2 servers - one that serves our frontend files and a WebSocket server. So we will have to convert both to running over HTTPS / TLS.

I want to take time in this lecture and use mkcert to generate certificates in order to run your localhost frontend server (using Live Server) over HTTPS.

Now that Live Server is up and running, the final piece of the puzzle is to convert our WebSocket server to run over TLS / HTTPS.

In this course we're using Node.js, so let's use the native https module and the native fs module to turn our WebSocket connection into one using HTTPS.

Let's get crackin'

The next goal I want you to achieve is being able to parse and receive incoming data sent from a client.

I want to now create a app_v3 file that we can use for our next milestone.

In Node.js, when handling WebSocket connections using the HTTP module, the 'upgrade' event is emitted when the server receives an HTTP request with an Upgrade header. This event provides us with a "socket" object that is crucial for establishing the WebSocket connection.

In this lecture you will learn:

1. The socket object passed to the 'upgrade' event handler is an instance of the net.Socket class, which is part of the net module.

2. net.Socket inherits from the stream.Duplex class, which means it implements both the readable and writable interfaces of a stream.

3. By inheriting from stream.Duplex, the net.Socket object can be used for both reading and writing data simultaneously, enabling full-duplex communication required for WebSocket connections.

In Node.js, the socket object refers to an instance of the net.Socket class, which is part of the net module.

Now that we are ready to go, let's listen for the 'data' event and define what happens in our callback function. As you'll learn, I want to define a receiver object that we can keep track of all the chunks of data received. Although we won't strictly need this now, we want to set up our code so that we can later receive large amounts of data and WebSocket fragments.

In Node.js, when using the socket object in the context of WebSocket connections (particularly during the 'upgrade' event), you can listen for several events that are emitted by this socket. The socket object, which is an instance of net.Socket, inherits from the EventEmitter class, allowing it to emit and respond to various events.

The end event is emitted when the other end of the socket has finished sending data. It indicates that the connection has been closed from the remote side.

In this lecture let's start creating our receiver object. I will use JavaScript's class syntax to define our factory function, even though I don't have to. In fact, it'll be a great exercise for you to refactor the code at the end of this course to work with pure native function constructors in JavaScript.

In order to write awesome code, its best to sit back and visualize what it is we're working with and what we are trying to achieve.

In this lecture I want to show you the various tasks that will be involved in extracting payload data from a WebSocket data frame.

As you'll see, there are effectively four steps to extracting data from a WS frame:

1. get frame header information in the first 2 bytes

2. get the payload length indicator

3. get the masking key

4. finally, get the actual payload data.

This will be managed by our looping engine.

In this lecture I want to code up the looping function that will be responsible for handling and directing our node.js process to execute the correct task.

By the end of this lecture you would have extracted the first 2 bytes of data from the Websocket frame. Pretty cool, huh?

Well done for getting this far.

When dealing with WebSockets, buffers are essential for parsing and constructing WebSocket frames, which are binary structures containing headers and payload data. For example, when receiving a WebSocket message, you use buffers to extract the frame headers, payload length, and masking key, and then to unmask the payload data using XOR operations.

Working with buffers is essential for managing the low-level details of WebSocket communication, ensuring that data is correctly parsed and transmitted between the client and server.

Before we get back to code, I want to illustrate how the letter "a" is sent over the wire. Did you know that it will take up 7 bytes of data? I will show you how this is broken up as a WebSocket data frame.

I want to take this time to open the debugger tool and analyze what we've received so far.

Its time to start extracting header information from our WebSocket frame. In this lecture I'll show you how to use Bitwise operators to extract the first bit (the FIN bit) from our first byte of data.

To extract WebSocket frame header information using native Node.js without any external libraries, you need to understand the structure of a WebSocket frame and use bitwise operators to decode the header.

Know that you know how Bitwise parsing works, let's use the & operator to extract the data we need.

You've completed the first task of this section - that is, extracting the first 2 crucial bytes from a WebSocket frame and have extracted the FIN, MASK, OPCODE and initial LENGTH fields.

The next step is to calculate the actual length of the payload.

Well done for extracting the first 2 bytes of information from a WS frame. The next step is to now calculate the exact size of the payload data contained within the first fragmented message.

The RFC defines 3 categories of payload length sizes, and they have set appropriate flags in order for us to figure that out.

The WebSocket protocol organizes message sizes into three distinct categories to optimize data transmission. Small messages, under 126 bytes, have their length embedded in the initial two bytes of the frame header. Medium messages, between 126 and 65,535 bytes, need two additional bytes to denote their size. Large messages, exceeding 65,535 bytes, use eight extra bytes to specify their length, enabling support for messages up to 2^63-1 bytes. This method ensures that smaller messages are handled with minimal overhead, while larger messages are accurately represented.

Calculating the payload length of a WebSocket frame is not trivial due to the complexity introduced by varying frame header sizes, which depend on the payload size. In this lecture let's implement our own logic to calculate the exact payload length of our websocket frame.

The _getLength method is essential for calculating and returning the _framePayloadLength property, which is critical for correct frame parsing, resource management, performance optimization, and compliance with the WebSocket protocol. This property provides a unified representation of the payload size across all scenarios, ensuring that the server can handle frames of varying sizes efficiently and reliably.

A quick summary and recap of how the _getLength() method works.

In the previous lecture I used the readUInt16BE() method. I want to take a break and explain to you what big endian means.

I want to define our processLength() function in this lecture, where we perform some basic length checks.

You are almost done. You've extracted the first 2 bytes of the WS frame. You've also extracted all frame header info necessary to calculate the length of the payload.

The last step before extracting payload data is to consume the masking key.

Good luck!

As you know, before we can consume the payload, we need to ensure that we have decoded or "unmasked" the payload. To do this, the first step is to extract the masking key that is part of the websocket frame.

Well done on getting this far. In this lecture we will start focusing on the final task that we need to complete in order to finish this section - extracting the actual payload.

Let's start working on our getPayload() method.

When we defined the getPayload() function, the first thing we had to do was check whether we have enough data in our custom buffer variable to consume a full frame of data.

If we don't have enough data, then we have to jump out of the receiver object and wait for another chunk of data to be received on the socket object.

I want to loop through our _buffersArray and extract the amount of chunks necessary to make up one full WebSocket frame.

You may be wondering why I have decided to create a new function called _consumePayload() when we have already defined a function called _consumeHeaders() to extract and consume bytes from a ws frame.

Well, let me explain why in this lecture.

In this lecture we will using the client's masking key, and the XOR operator to unmask the payload data.

The index variable keeps track of the current position in the payload data. The % 4 operation ensures that the index wraps around to 0 after reaching 3, thus cycling through the 4-byte masking key.

In this lecture I want to create a persistent fragments array and check for more frames (FIN bit check)

Having a fragments array helps us keep a persistent array of all frames received from the client.

In this lecture I want to use the Debugger tool to examine our code and logic for small payloads.

In the previous lecture we encountered an error where we did not update our total bytes read. I will fix it here, and continue to analyze our logic and code.

When we want to test medium and large payload sizes, I want an easy way for us to do so. Manually copy/pasting large blocks of text is tedious. That's why in this lecture I want to create a button that we can click on that does this for us.

I want to examine the case where the client sends 50,000 bytes of data to the server.

All of our code logic related to medium sized payloads (i.e. where our _initialPayloadSizeIndicator variable is set to 126) should execute.

The values 195 and 80 in your buffer are byte values or unsigned 8-bit integers, represented in decimal form.

Binary and decimal are different number systems. Binary uses base 2 (0s and 1s), while decimal uses base 10 (0 through 9).

That's why I had to call the readUInt16BE() method - to represent our binary data into number format.

For the first time in this course, we can finally test our code.

I want to test the scenario where the client sends 150,000 bytes of data to the server in one WebSocket message.

As you'll see: 

• the client packages this WebSocket message into 2 fragments

• the first frame payload size sent is 131,000 bytes

• due to network constraints, the first chunk received is only 65k bytes in size. This means we don't even have enough data yet to consume our first frame.

In summary, BigInt is a new data type in JavaScript that allows for the representation of very large integers with arbitrary precision, solving the limitations of the standard Number type. The n suffix is used to denote a BigInt value, ensuring that it is treated differently from a standard Number.

In short, chunks are network segments, frames are WebSocket-specific, and messages can be made up of multiple frames. This helps in handling large data efficiently over the network.

I want to now pick up exactly where we left off in the previous lecture. As you know, we have only received a chunk of 65k bytes, but our full frame payload size is 131,000 bytes.

This means we have to test our code to ensure that we jump out of the receiver object and wait for additional chunks of data to be fired on our socket object.

Let's finish off with the debugger session on our large payload. In this lecture you'll see how we examine the FIN bit and receive the last frame of data and how we combine everything into our _fragments array.

A quick lecture to add some opcode checks and improve some comment descriptions.

This is an advanced topic, but as I keep saying, I want you to become a Grandmaster at WebSockets.

I want to show you via code and a practical example how the debugger vs running node.js live can produce different chunk sizes.

If you will recall from the previous lecture, we had 58 bytes in our _buffersArray and we then use the _getInfo() method to consume the first 2 bytes of header information.

BUT what happens if by chance, we are only left with 1 byte of data? or even 0 bytes? In other words, what happens if we don't have enough data to consume the first 2 bytes of header info? 

We will get thrown an error.

So in this lecture let's just fix that quickly, by telling our engine to wait for an additional data chunk.

Well done for completing this section of the course. It has not been easy, but I'm confident you've learnt a TON. Attached are the coding files we've done thus far.

The next goal I want you to achieve is being able to parse and receive incoming data sent from a client.

I want to create a new version app file so that we can start concentrating on writing code for our _sendEcho() function.

The first part of our mission is to correctly allocate enough space in our frame buffer to represent the entire websocket message.

In WebSocket communication, the header of a frame includes a variable-length field to indicate the payload length. This field is necessary because the payload can vary significantly in size, and a fixed-length header would be inefficient. The variable-length header allows for compact representation of small payloads while accommodating larger ones without excessive overhead.To calculate the size of this variable-length header, you start with the minimum 2 bytes that include the FIN and opcode byte, and the mask and length indicator byte. If the payload length is between 0 and 125, this 2-byte header is sufficient. However, if the payload length is between 126 and 65535, an additional 2 bytes are added to represent the 16-bit length. For payloads larger than 65535 bytes, an additional 8 bytes are used to represent the 64-bit length. For client-initiated frames, an extra 4 bytes for the masking key are also included. This dynamic approach ensures efficient use of bandwidth while supporting a wide range of payload sizes.

The payloads in the WebSocket frame header are variable in size to efficiently accommodate a wide range of payload lengths. This approach allows for compact representation of small payloads, using just the initial 2 bytes of the header for lengths up to 125 bytes. For larger payloads, additional bytes are used to represent the length: 2 bytes for lengths between 126 and 65535 bytes, and 8 bytes for lengths greater than 65535 bytes. This variable-length encoding ensures that the overhead is minimized for small messages while still supporting large payloads, making the protocol flexible and efficient

You now have all the required information necessary (the 2 bytes, plus any additional bytes required to represent the payload length) to construct the blueprint of the frame that our server will send back to the client.

I am now going to create the first byte of the binary frame. This means we have to correctly set the FIN, RSV bits and OPCODE.

When a server sends text data over a WebSocket connection, the binaryType property does not affect how the text data is received. The binaryType property only determines how binary data is represented on the client side.

Bitwise shift operators are low-level operators that manipulate the individual bits of an integer by shifting them to the left or right.

We have all the information required to now populate our frame header with data.

In this lecture we will access our socket object (that represents our websocket connection) and send the frame to the client using the write() method.

I want to test whether our socket.write(frame) method has worked as expected. I am sure you will be pleasantly surprised.

A Blob in the context of web APIs and a Buffer in Node.js share some similarities but also have distinct differences.

The socket.write() method for WebSockets requires the data to be in the form of a Buffer. This is because WebSockets use a specific binary frame format that includes headers and payload, which must be constructed manually. You need to manually construct the WebSocket frame according to the WebSocket protocol specification. This involves creating a Buffer that includes the necessary headers and the payload.

Creating a reset() function to reset property values on the receiver object

I want to step through the code related to our _sendEcho() function so that you understand, REALLY understand, what we've done.

Fragmentation is an implementation detail that helps manage memory and performance. The key points to consider are:

• Random Fragmentation: Fragmentation can occur randomly, making it essential to handle it on the server side.

• Optimization: The WebSocket API optimizes memory usage by compressing data and generating fragments, which are then written to the remote endpoint as needed.

While the exact details of fragmentation might be complex, the crucial aspect is to ensure that your server can handle fragmented messages effectively. This version clarifies the reasons behind message fragmentation and emphasizes the importance of handling it on the server side.

The final step is to listen on the client side for the 'message' event and then extract the data and display it inside of the data table.

In summary, while there are multiple ways to read a Blob, using FileReader offers significant advantages due to its flexibility and event-driven nature. Whether you need to read binary data, text, or process large data sets in chunks, FileReader provides a robust and manageable solution.

Attached are the project files.

The next goal I want to code with you is to deal with websocket closures. I can't wait.

Before we start coding our closure function, i want to set up our project file and define our next mini-goal

To close a websocket connection, a closing handshake needs to be performed.

In this lecture let's extract the payload information of the close frame received from the client.

Both peers (client and server) have to send close frames.

The WebSocket protocol, as specified in RFC 6455, defines a specific frame structure for control frames, including the Close frame. A Close frame, identified by the opcode 0x8, is a control frame used to indicate the closure of a WebSocket connection. This frame may contain a payload, which includes a status code and an optional reason for the closure. The frame structure for a Close frame consists of a header with the FIN bit set to 1 (indicating it is the final frame of the message), the opcode set to 0x8, and a payload length field followed by the payload data. The payload data includes a 2-byte status code and an optional reason string. This structured approach ensures that both endpoints can clearly understand the reason for the connection closure and take appropriate actions to close the underlying TCP connection

A close frame contains a header and and optional payload.

In this lecture I want us to construct a closure code payload buffer, that we will later insert into our final close frame.

Closure codes in the WebSocket protocol are standardized values used to indicate the reason for closing a WebSocket connection. These codes help in maintaining state consistency and providing meaningful feedback to both the client and server.

Let's complete the construction of our close frame and send it to the client.

Let's see our code work in action. As you'll discover, it is not quite finished because the server has still not shut down the underlying TCP connection.

In this lecture you will learn and master the reason behind the RFC requiring the server to end the TCP connection immediately after sending back a close frame.

Let's deal with ping and pong frames, and the scenario when a client sends data larger than our maximum defined size

• No Client-Initiated Pings: The WHATWG WebSocket specification does not provide for client-initiated ping frames.

• Server-Initiated Pings: The server typically initiates the ping process to ensure the connection's health and liveness.

• Consistency and Control: This approach maintains consistency and control over the connection's health checks, ensuring reliable and active connections.

In summary, since the WHATWG WebSocket specification does not cater for client-initiated pings, it is the server's responsibility to initiate the first ping to check the connection's health and liveness.

The purpose of WebSocket ping and pong frames, despite TCP having its own keepalive mechanism, can be explained by several key differences and requirements.

As you know, when a close event is fired, the websocket api gives us access to an object - this object is a CloseEvent object that inherits from the Event interface.

On this object, there is a reason property that we can access that contains our response message from the server.

Let's close the connection if the client has not correctly set the masking bit.

We can implement our own code and policies and send back close frames in response.

When a user clicks on the "close" button, we are currently not displaying the server response. Let's do that now.

A few fixes in this lecture.

Right now, we have a basic "required" attribute on the front-end. Of course, a user can always bypass this and submit an empty text field to the server. For this reason, you should always implement server-side logic.

In this lecture let's check the frame payload and if its zero, let's close the WS connection.

Let's catch the closure code of 1001 and then gracefully close the websocket connection, rather than letting the server crash.

Final project files

A huge WELL DONE for completing this course and sticking with me until the very end.

Quick suggestions for what course I think you should take next