Creating an HTTP Server from Scratch with Node-addon-api, Libuv, and Milo

Welcome, everyone. Today, we're going to talk about Node.js and specifically how to create an HTTP server from scratch. My name is Marco Ippolito. I'm a Senior Developer Experience Engineer at NearForm. I'm also a Node.js core contributor and open-source enthusiast.

So let's get started. What I mean from scratch is literally from scratch. So we will create a native add-on, and we will not use Node.js standard library. So what we will do is call libuv directly and write a bit of C++. But even if you are not a C++ developer, don't be scared because it will be very simple.

So what is a native add-on? A native add-on is a module written in C++ or in C, but it can also be written in Rust that extends some of the low-level functionalities of Node.js, such as libuv. If you don't know what libuv is, we will talk about it later in detail. And also V8, which is the JavaScript engine, Zlib, and many other libraries that compose Node.js. So this native add-on allows us to access the system that we are using, and we could normally not access it in JavaScript.

To create a native add-on, we need a library called Node.addon-api. Node.js has a bunch of APIs that are public and are released. And this package provides the header files to make the development much, much easier. And they are also stable, which means that if you update the Node.js versions, they're not going to break. They're going to be stable. And it's also maintained by the Node.js team. So as you can see, it has quite a few downloads on NPM.

The other library that we need is Node.jyp. So historically, Node.js add-ons have been built with Node.jyp. It was used by Chromium at the beginning, and it was adopted in the early days of Node.js. But you can also use CMake or whatever tool you use for building C++ applications. And with this build system, it will generate a .node file that we can call from JavaScript. And the final one is bindings. This is a very important one because it's a helper module that allows us to import the .node add-on into our JavaScript file, just like you would require or import a JavaScript module. With bindings, you can import a native add-on. So let's see the project structure.

We will see a bit of code, but it will be quite simple. So to create the native add-on, you first need to add in the package.json that you are exporting a .jp file. So we set .jp file to true, and for this example, we set the type module to use ESM. So this allows NPM to know that this is a native add-on and it will unlock some functionalities like build on during installation, and it's a special mode for NPM.

Then we will need to have two scripts for build and clean. With the clean one, just deletes the build folder. And then we have these three dependencies that we just talked about. In our source folder, we had the C++ files. So we have an add-on file which basically exports our add-on. So please have a look at the export object. It's basically the same thing as doing module.export. It's the same object, just passed in the C++ side. In this talk, you will see a lot of similarities, and there is a lot of C++ code that is just actually JavaScript code. They behave in the same way, and I will show you the one-to-one comparison.

So once we have declared our add-on module, then we have to export our class. So we will export TCP socket inbound, TCP socket class. As I said before, what we are doing in C++ is basically exporting this inbound TCP socket. We will talk about what inbound TCP socket is and why it's important to create an HTTP server.

So now that we have declared our source files, we need to bind them. So we create a binding.gwp file and we add the C++ files inside sources. So we have the add-on C++ and inbound TCP socket C++ file. And then we write as target name, the name of our add-on. In this case, we want to export it as inbound TCP socket. This will be important because when we go to import it with the bindings, we have to write the same name. So we are doing bindings inbound TCP socket. And now we can just use the class that we have created previously and we can instantiate it with a constructor. Don't worry about the code, we will see in detail later.

So let's talk a bit about the TCP socket. So what is our TCP socket? So we know that HTTP is an application layer protocol. So it's technically independent from the transport layer.

So we could write HTTP through TCP or UDP in the case of HTTP3. In this case, we use a TCP socket to exchange that data from the server and the client. So data will be flowing through this socket. And we need to bind the socket to an address, so an host and a port of our machine and listen to incoming connections. So for this, we need LibuV. LibuV is a library that is very important because it abstracts all the difference between different platforms like Windows. So on Windows, sockets are implemented in a different way. They have slightly different features. And also on the other platforms that Node.js supports, they are all different. So LibuV standardizes those API and allows us to just use a function that works everywhere. So it's a really amazing library and we will use some APIs later. On the right, we can see how TCP server works. So first we need to bind it, then we need to start listening for incoming connections. We need to accept incoming connections and then we can write a read and write from the socket, so transfer data from the client and server. So let's start. On the side, on the left side, we will have the JavaScript code and on the right side, we have the C++ code and you will see we're bouncing through JavaScript and C++. To create our socket, we use the constructor that we talked about later and we pass the hostname and port to it. And then on the C++ layer, we just create a class called inbound TCP socket and we save this port and this hostname as a class instance.

Then what we do is create a listen function and pass a callback to it. So we have a request, a response and error. So this function will be invoked every time there is new data coming on the TCP socket. And as you can see in C++, this callback is received inside the listen function and it will be called callback. So now that we have a callback that will be invoked every time we receive data, we need to start listening for this data. And for this, we call uvlisten, which is the libuv function. And as I said before, the amazing thing is that this will work on Windows, on POSIX compliant platforms, on Android. This will work almost everywhere that libuv supports and we don't have to write different code based on the platform. So when we start listening, we will receive data. So imagine that now we send a fetch, actually a HTTP post to our server, to our socket. And what we do is we receive a request that is basically creating a request object and adding as the property data, the data that we have read from the socket. And then we create a response object where we add the function write so that we can read and write on the same socket so that the client will have a response.

And then we invoke the callback that we have passed to C++ and we will match the signature. So it will be a request, response, and undefined because there is no error. And it will be the same thing as doing as calling a function in JavaScript. All this code is actually the same thing because on how V8 APIs are called in the background by Node API. So we're just writing JavaScript, but in C++. So this is what we have.

This is what we read from the socket. This is the raw HTTP message. It's just a string. And so we need to parse this string to manipulate it and to answer. So we will see how to do that later. But for now, we just write a response, a raw response to a socket, and we'll just write some raw HTTP. And what we will do again, we call the function response.write. We parse the raw response. And on the C++, we get data as a string. And then we write it on socket. Back to the client. And then we close the socket because we have responded to the client. And the client will read hello world. So as you've seen, it's a ping pong. It's data flows through JavaScript and through C++ both ways so that we can read data from our operating system, manipulate it in JavaScript, and send it back into the low level APIs.

So now we have created the socket, which is the internal mechanism of an HTTP server. So it's the raw part. Now we need to create a high level abstraction and actually start implementing HTTP methods and etc. So the HTTP server, what we need to do is we need to parse and validate the request that we have received from the socket. We want to know that we have received some valid HTTP and we want to be able to manipulate it as an object. We want to be able to recognize what are the headers, what are the methods, what is the body. So we need to parse it. And we also need to write the response in a valid HTTP format. We cannot just send a string like we did before with the socket.

And we also have to consider that there are three major versions of HTTP. There is HTTP 1.1, HTTP 2, and HTTP 3. They are different in some of the features. The most used one is obviously HTTP 1.1. But for the sake of this proof of concept, we will not implement HTTP 2 and 3.

So for the parser, we use Milo, which is a HTTP parser created by my colleague Paolo Insogna. We will see about it later. It's still experimental and it's written in Rust. And also we will bundle it as a WebAssembly module. So Node.js actually has HTTP parser called LLHTTP. But it's used inside Undiji for example, but it's also used inside Node. So we could also use that. But for this proof of concept, we will use Milo.

So we will instantiate the new InboundSocket class. So the TCP socket inside the class HTTPServer. And then we will have the same function, listen. But now we will parse the data that we receive from the socket. So if you want to know more about how HTTP parser works, please go watch the talk of my colleague Paolo. He will be speaking here at Node Congress. So you will know everything about HTTP parsers.

So now we take the data that has been parsed as an object and we will wrap it inside a request object for compliance with the web standards. And then we will see we will send the response back to the client. So here we will parse the response that we have written and send it back to the client or to the socket.

So how does it work? Very similarly to the TCP socket that we have created at the beginning, we instantiate the new server. We pass the hostname and the port. Then when there is data on a request, we will send the response and this response will be received to the client.

As an example, we do we execute a fetch to our HTTP server passing Hello Marco. And then we can see from the console log that we've seen before on the request that here in the body that is Hello Marco. And these are all the parsed HTTP with all the headers and the HTTP method protocol, et cetera. And then we will write we will see what we have responded, which is Hello World. And the response of the fetch will be Hello World.

This was the magic behind how an HTTP server works. This was like simplified by a lot. This is just the basic workings. And as a disclaimer, this is a proof of concept. You can find the full project on my GitHub. It's a full project where you can test this by yourself. You can investigate and see how actually works. But the interesting stuff is how to create how easy it is to create an add-on and how easy it is to communicate with low-level APIs.

So also, if you're interested in working with Node.js and you like HTTP stuff, we have a working group. You can find it on Node.js web server framework. We talk about HTTP, the future of Node.js HTTP module and very interesting stuff around HTTP, but also TCP about networks.

That was it. Thanks to Nierform for allowing me to work on Node.js. And thank you very much. You can find all my information on this QR code. Please reach out if you want some more content or information about this topic.