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

Rate this content
Bookmark

Let's explore the magic behind Node.js and create a simple http server! We'll go step-by-step, understanding how libuv makes node asyncronous and how Milo helps our server parse HTTP request. We'll use node-addon-api to create the bridge between c++ and javascript.                                       

Marco Ippolito
Marco Ippolito
18 min
04 Apr, 2024

Comments

Sign in or register to post your comment.

Video Summary and Transcription

Today's Talk focuses on creating an HTTP server from scratch using Node.js and native add-ons. The process involves implementing a TCP socket using LibuV for data exchange between the server and client. The Talk also covers invoking callbacks, creating a high-level abstraction for the HTTP server, and parsing HTTP data using an experimental HTTP parser called Milo. The project serves as a proof of concept, showcasing the ease of creating add-ons and interacting with low-level APIs in Node.js.

Available in Español

1. Introduction to Node.js and Native Add-ons

Short description:

Today, we're going to talk about Node.js and specifically how to create an HTTP server from scratch. We will create a native add-on that allows us to access the system that we are using and extend the low-level functionalities of Node.js. To create a native add-on, we need the Node.addon-api and Node.jyp libraries, along with the bindings module. Let's see the project structure.

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.

2. Creating a Native Add-on and TCP Socket

Short description:

To create the native add-on, first add in the package.json that you are exporting a .jp file. Set the type module to use ESM. Then, create two scripts for build and clean. Include the three dependencies we talked about. In the source folder, you'll find the C++ files. Declare the add-on module and export the TCP socket inbound class. Bind the source files and use the class with a constructor. The TCP socket is independent from the transport layer.

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.

3. Using a TCP Socket and LibuV

Short description:

To exchange data between the server and the client, we use a TCP socket. LibuV is a library that abstracts platform differences and provides a consistent API for working with sockets. The TCP server binds to an address and listens for incoming connections. It accepts connections and enables data transfer between the client and server. In JavaScript, we create a socket using a constructor and pass the hostname and port. On the C++ layer, we create a class called inbound TCP socket. We implement a listen function that invokes a callback whenever new data is received. The libuv function uvlisten allows us to start listening for data on the socket. When data is received, a request object is created with the data from the socket, and a response object is created to read and write on the same socket for client responses.

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.

4. Invoking Callback and Creating HTTP Server

Short description:

When invoking the callback in C++, it matches the signature with request, response, and undefined. The code is the same as calling a function in JavaScript. The raw HTTP message is a string that needs to be parsed and manipulated. We write a raw response to the socket and send it back to the client. Data flows through JavaScript and C++ in both directions. Now we need to create a high level abstraction for the HTTP server to parse and validate requests, and write responses in a valid HTTP format.

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.

5. HTTP Versions and Parser

Short description:

There are three major versions of HTTP: 1.1, 2, and 3. For this proof of concept, we will not implement HTTP 2 and 3. We use Milo, an experimental HTTP parser written in Rust and bundled as a WebAssembly module. We instantiate the new InboundSocket class and parse the data received from 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.

6. Wrapping Data and Server Instantiation

Short description:

After parsing the data, we wrap it in a request object and send the response back to the client or socket. Similar to the TCP socket, we instantiate a new server and handle incoming requests. As an example, executing a fetch to our HTTP server returns the parsed HTTP data with headers and the response. This is just the basic workings of an HTTP server. The project is a proof of concept available on my GitHub, showcasing the ease of creating add-ons and interacting with low-level APIs. If you're interested in Node.js and HTTP, join our working group on Node.js web server framework.

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.

Check out more articles and videos

We constantly think of articles and videos that might spark Git people interest / skill us up or help building a stellar career

It's a Jungle Out There: What's Really Going on Inside Your Node_Modules Folder
Node Congress 2022Node Congress 2022
26 min
It's a Jungle Out There: What's Really Going on Inside Your Node_Modules Folder
Top Content
Do you know what’s really going on in your node_modules folder? Software supply chain attacks have exploded over the past 12 months and they’re only accelerating in 2022 and beyond. We’ll dive into examples of recent supply chain attacks and what concrete steps you can take to protect your team from this emerging threat.
You can check the slides for Feross' talk here.
Towards a Standard Library for JavaScript Runtimes
Node Congress 2022Node Congress 2022
34 min
Towards a Standard Library for JavaScript Runtimes
Top Content
You can check the slides for James' talk here.
Out of the Box Node.js Diagnostics
Node Congress 2022Node Congress 2022
34 min
Out of the Box Node.js Diagnostics
In the early years of Node.js, diagnostics and debugging were considerable pain points. Modern versions of Node have improved considerably in these areas. Features like async stack traces, heap snapshots, and CPU profiling no longer require third party modules or modifications to application source code. This talk explores the various diagnostic features that have recently been built into Node.
You can check the slides for Colin's talk here. 
ESM Loaders: Enhancing Module Loading in Node.js
JSNation 2023JSNation 2023
22 min
ESM Loaders: Enhancing Module Loading in Node.js
Native ESM support for Node.js was a chance for the Node.js project to release official support for enhancing the module loading experience, to enable use cases such as on the fly transpilation, module stubbing, support for loading modules from HTTP, and monitoring.
While CommonJS has support for all this, it was never officially supported and was done by hacking into the Node.js runtime code. ESM has fixed all this. We will look at the architecture of ESM loading in Node.js, and discuss the loader API that supports enhancing it. We will also look into advanced features such as loader chaining and off thread execution.
Node.js Compatibility in Deno
Node Congress 2022Node Congress 2022
34 min
Node.js Compatibility in Deno
Can Deno run apps and libraries authored for Node.js? What are the tradeoffs? How does it work? What’s next?
Multithreaded Logging with Pino
JSNation Live 2021JSNation Live 2021
19 min
Multithreaded Logging with Pino
Top Content
Almost every developer thinks that adding one more log line would not decrease the performance of their server... until logging becomes the biggest bottleneck for their systems! We created one of the fastest JSON loggers for Node.js: pino. One of our key decisions was to remove all "transport" to another process (or infrastructure): it reduced both CPU and memory consumption, removing any bottleneck from logging. However, this created friction and lowered the developer experience of using Pino and in-process transports is the most asked feature our user.In the upcoming version 7, we will solve this problem and increase throughput at the same time: we are introducing pino.transport() to start a worker thread that you can use to transfer your logs safely to other destinations, without sacrificing neither performance nor the developer experience.

Workshops on related topic

Node.js Masterclass
Node Congress 2023Node Congress 2023
109 min
Node.js Masterclass
Top Content
Workshop
Matteo Collina
Matteo Collina
Have you ever struggled with designing and structuring your Node.js applications? Building applications that are well organised, testable and extendable is not always easy. It can often turn out to be a lot more complicated than you expect it to be. In this live event Matteo will show you how he builds Node.js applications from scratch. You’ll learn how he approaches application design, and the philosophies that he applies to create modular, maintainable and effective applications.

Level: intermediate
Build and Deploy a Backend With Fastify & Platformatic
JSNation 2023JSNation 2023
104 min
Build and Deploy a Backend With Fastify & Platformatic
WorkshopFree
Matteo Collina
Matteo Collina
Platformatic allows you to rapidly develop GraphQL and REST APIs with minimal effort. The best part is that it also allows you to unleash the full potential of Node.js and Fastify whenever you need to. You can fully customise a Platformatic application by writing your own additional features and plugins. In the workshop, we’ll cover both our Open Source modules and our Cloud offering:- Platformatic OSS (open-source software) — Tools and libraries for rapidly building robust applications with Node.js (https://oss.platformatic.dev/).- Platformatic Cloud (currently in beta) — Our hosting platform that includes features such as preview apps, built-in metrics and integration with your Git flow (https://platformatic.dev/). 
In this workshop you'll learn how to develop APIs with Fastify and deploy them to the Platformatic Cloud.
0 to Auth in an Hour Using NodeJS SDK
Node Congress 2023Node Congress 2023
63 min
0 to Auth in an Hour Using NodeJS SDK
WorkshopFree
Asaf Shen
Asaf Shen
Passwordless authentication may seem complex, but it is simple to add it to any app using the right tool.
We will enhance a full-stack JS application (Node.JS backend + React frontend) to authenticate users with OAuth (social login) and One Time Passwords (email), including:- User authentication - Managing user interactions, returning session / refresh JWTs- Session management and validation - Storing the session for subsequent client requests, validating / refreshing sessions
At the end of the workshop, we will also touch on another approach to code authentication using frontend Descope Flows (drag-and-drop workflows), while keeping only session validation in the backend. With this, we will also show how easy it is to enable biometrics and other passwordless authentication methods.
Table of contents- A quick intro to core authentication concepts- Coding- Why passwordless matters
Prerequisites- IDE for your choice- Node 18 or higher
Building a Hyper Fast Web Server with Deno
JSNation Live 2021JSNation Live 2021
156 min
Building a Hyper Fast Web Server with Deno
WorkshopFree
Matt Landers
Will Johnston
2 authors
Deno 1.9 introduced a new web server API that takes advantage of Hyper, a fast and correct HTTP implementation for Rust. Using this API instead of the std/http implementation increases performance and provides support for HTTP2. In this workshop, learn how to create a web server utilizing Hyper under the hood and boost the performance for your web apps.
GraphQL - From Zero to Hero in 3 hours
React Summit 2022React Summit 2022
164 min
GraphQL - From Zero to Hero in 3 hours
Workshop
Pawel Sawicki
Pawel Sawicki
How to build a fullstack GraphQL application (Postgres + NestJs + React) in the shortest time possible.
All beginnings are hard. Even harder than choosing the technology is often developing a suitable architecture. Especially when it comes to GraphQL.
In this workshop, you will get a variety of best practices that you would normally have to work through over a number of projects - all in just three hours.
If you've always wanted to participate in a hackathon to get something up and running in the shortest amount of time - then take an active part in this workshop, and participate in the thought processes of the trainer.
Mastering Node.js Test Runner
TestJS Summit 2023TestJS Summit 2023
78 min
Mastering Node.js Test Runner
Workshop
Marco Ippolito
Marco Ippolito
Node.js test runner is modern, fast, and doesn't require additional libraries, but understanding and using it well can be tricky. You will learn how to use Node.js test runner to its full potential. We'll show you how it compares to other tools, how to set it up, and how to run your tests effectively. During the workshop, we'll do exercises to help you get comfortable with filtering, using native assertions, running tests in parallel, using CLI, and more. We'll also talk about working with TypeScript, making custom reports, and code coverage.