HTTPS Without Caddy or Nginx: The Built-in Web Server of API Maker

Intro

0:00 Here is the Built-in Web Server. API Maker serves HTTPS itself. There is no proxy in front, certificates renew by themselves, and every request takes the fastest path.

Calm Home today

0:14 Calm Home runs its APIs and its admin panel on API Maker. Like most teams, it put a reverse proxy in front for HTTPS: Caddy. Every visitor talks to Caddy, and Caddy talks to API Maker. It works. But every request is now handled twice, by two programs, and each one must be installed, updated, and watched.

A proxy in front

0:38 So what does that cost? A second program on every server. Each request is decrypted, read, and copied again. A hop adds time to every answer. Certificates are kept on one machine, in another format. And a restart drops the clients. With the built-in web server, API Maker answers HTTPS itself. A connection goes straight to the code of the API. The Linux kernel does the encryption. Every server shares the certificates.

1:09 And a restart refuses no one. In this video: why it is faster, turning it on, certificates, sites next to API Maker, the settings file, several servers, who keeps the settings, and security.

Why it is faster

1:25 First, let us see what a reverse proxy does with each request. It decrypts the bytes. It reads the request. It opens a connection to API Maker, or takes one it keeps. It copies the request across, then waits, and copies the answer back. Then API Maker reads the same request a second time. On a busy server, the proxy can use more processor time than API Maker itself. The built-in web server does none of that.

1:55 When a client connects, API Maker looks at three things, once: the port, the name the client asks for, and the protocol it speaks. A connection for the API then goes to the very same code as port 38246. Its requests are never looked at again. There is no copy, no second parser, and no hop. Then comes the encryption. The handshake runs in API Maker. Once it is over, the keys of the connection go to the Linux kernel.

2:28 The kernel encrypts and decrypts with the AES instructions of the processor, so API Maker reads and writes a plain socket, as if HTTPS were plain HTTP. Where the kernel has no TLS, on macOS or Windows, the encryption stays in API Maker. It is slower, but still correct. We measured it on the smallest Linode, with one shared processor, and the clients on a second one. Behind Caddy, HTTPS answered a few thousand requests a second.

2:59 With the built-in web server, it answered several times more, close to plain HTTP. And each request took a fraction of the processor time it took behind Caddy. A proxy was also good for one more thing: restarts. When you restart API Maker from the panel, or deploy a new version, the process keeps its listening sockets, and hands them to the new program. Clients that connect in the meantime wait a moment in the queue of the kernel, then they are served.

3:30 In our test, with requests flowing through the whole restart, not one failed.

Turning it on

3:36 There are four ways to turn it on, and they all write the same settings. The install script, with proxy builtin. API Maker Launchpad, with the reverse proxy set to API Maker, built in. The admin panel, on the page Web Server. Or a file you write by hand. Today, we use the admin panel. The page is for the root user. On the home of the root user, under Settings, open Web Server.

4:04 Each server of the installation keeps its own settings, so the page lists the servers first. This demo runs on a Mac, and only Linux has kernel TLS. The page says so, and why. This server has no settings yet. We turn the built-in web server on. Then, how are the admin panel and the API reached? Calm Home wants a domain for each. admin dot calm home dot dev for the panel, and api dot calm home dot dev for the API.

4:41 The web sockets share the API domain. Then an email for the certificate authorities. The list had four choices, so let us see them side by side. A domain for each, as here: one for the panel, and one for the API. One domain for everything: the routes of API Maker first, and the admin panel for the rest. The address of the server, with no domain: plain HTTP on three ports, or HTTPS on the address itself.

5:12 For an address, Let's Encrypt gives certificates of only six days, so API Maker renews them every few days. A domain gets the usual ones, as long as the ones of Caddy. And on port 80, every request is sent to HTTPS, except the challenges of the authorities. A few settings below decide the details. HTTP is sent to HTTPS. Strict Transport Security is on, for the admin panel only by default.

5:43 HTTP two is on for the panel and the sites, where browsers load many files at once. The API stays on HTTP one point one, because that is the faster way API Maker serves. The ports are 80 and 443. And you list the addresses that the admin panel answers, checked once per connection. Before anything runs, Check asks the server to read the settings exactly as it would. They can be used.

6:14 Save and apply writes them, and the page waits until the server runs them. It names the revision that runs. In the table, the server is running, on ports 80 and 443.

Certificates

6:27 Now, certificates. For each domain, API Maker gets a free certificate from Let's Encrypt. Before it orders, it checks that the domain points to this server. So a name whose DNS is not ready never uses up the failed orders that an authority allows. It answers the challenge, and keeps the certificate in its MongoDB, with the key encrypted. Every server of the installation shares it. One server orders, and the others load it.

6:57 It renews by itself, when the authority says. And ZeroSSL takes over when Let's Encrypt fails. Let us look at the certificates of this server. On this Mac, the domains of Calm Home point nowhere in the real DNS. So the page says that both names are waiting for DNS, with the reason, and nothing was ordered. Many companies already have their own certificate, often a wildcard. Calm Home has one for star dot calm home dot dev.

7:26 Click Add own certificate. Give a name, the chain, and its private key. The server writes them into its folder, with the key readable by the server alone. Once saved, the names it covers use it, and nothing is ordered for them. It says yours, valid until next year. Let us check it from a terminal. A call to the API uses TLS one point three, with AES, and HTTP one point one, as the API prefers.

8:04 The answer comes from API Maker itself. On plain HTTP, the request is sent to HTTPS, with a 308. And the admin panel speaks HTTP two. Now the browser. At admin dot calm home dot dev, over HTTPS, API Maker itself serves the admin panel. We sign in as before, and the page Web Server shows the server running, with its certificate.

Sites

8:33 A server rarely serves only an API. Calm Home also has a landing page, and a journal written with another program. So the built-in web server serves sites, next to API Maker. It serves static files, even single page apps. It can be a reverse proxy to other programs, with health checks and web sockets. It serves an SSR website of API Maker, at the root of a domain. It can redirect.

9:02 Or it can use your own routes. A site has its own domains, or its own port, and never takes those of API Maker. Open Sites. Click Add a site. Name it the landing page, as static files, on www dot calm home dot dev, and on calm home dot dev itself. Give the folder of its files. Click Keep. Then add a second site: the journal. It is a reverse proxy, on its own domain, to the program on this server.

9:42 Click Keep, then save and apply. The page shows the target of the journal is up. Let us open them. Here is the landing page, from its folder, over HTTPS. Here is the journal, from its own program, through the reverse proxy. And the access log of the page has a line for every request of the sites. The API keeps its own logs, as before.

The file of the settings

10:15 Everything the page does lands in one file. The File tab shows edge dot json, as the server reads it. Comments are fine. But say we make a typo in a key. Check refuses it, with the file and the place. A key that the server does not know is an error, so a typo never stays silent. We undo it, and the settings can be used again. A file that the server cannot apply is never half applied.

10:42 The settings that ran keep running. The settings live in one folder on each server: edge dot json, one file for each site, and the status that the server writes. API Maker watches the folder, and applies a change within two seconds, with no restart. New settings apply to new connections. An open connection keeps the settings it started with. From a terminal, edge check reads a folder without changing anything, and edge status says what runs.

Several servers

11:15 As Calm Home grows, it runs API Maker on several servers. Usually, a load balancer in front shares the requests. The built-in web server of one server can do it, as a gateway. Each new connection goes to one server, chosen once. It can be the one with the fewest connections, each in turn, the same client to the same server, the first one up, or a random one. Its bytes then go from socket to socket, inside the kernel.

11:44 A small header, the PROXY protocol, tells the other server who the client is. That server trusts this header only from the addresses it lists. Every server is checked every ten seconds, and a server that is down gets no new connection. A second server, video2, has joined the installation. First, on video2, turn the built-in web server on, only for its sites, and let it take PROXY headers from video1 only.

12:17 It is saved. Then on video1, add the other servers: video2, by its address. Each connection goes to the next server, in turn. And save. Now clients call the API over HTTPS, each on a new connection. The page of video1 shows video2 is up, and how many connections it sent there. If video2 stops, the next check finds it down, and every new connection stays on video1. Clients that keep a connection open stay where they are, because the sharing is per connection, not per request.

Who keeps the settings

12:53 Several tools can write these settings, so each file says who keeps it. When Launchpad keeps them, the page shows them as read only, so a change here is not lost at the next deployment. Take over asks first, then lets you change them here. Launchpad writes its own again the next time it deploys this server, and the settings of the page are kept in the backups of the folder.

13:18 On a new server, you rarely open this page at all. The install script takes proxy builtin, with your domains, or HTTPS on the address. It loads the TLS module of the kernel, now and at every boot. And coming from Caddy, it takes over the valid certificates of Caddy, so there is no new order, and no wait. In Launchpad, the reverse proxy of a server that runs API Maker can be API Maker, built in.

Security and limits

13:46 A few rules keep it safe. Private keys are encrypted in MongoDB, and never appear in logs, the status file, or answers. With kernel TLS, the keys of each connection live in the kernel, not in API Maker. A connection of a site or of the panel serves only its own names. A request for another site gets a 421. And a static site never serves a file outside its folder, or a hidden file.

14:14 And there are a few limits, to plan around. HTTP three is not served. A wildcard domain needs your own certificate, because there is no DNS challenge. And kernel TLS needs Linux. macOS and Windows keep the encryption in API Maker.

Recap

14:33 To sum up. API Maker serves HTTPS itself, with no proxy in front. A connection is decided once, and the kernel does the encryption. Certificates come by themselves, and every server shares them. Sites, a gateway, and live settings come with it. Turn it on from the installer, from Launchpad, or from this page. Next: scaling out to several servers. API Maker. Build faster, spend smarter, deliver better.