Commit 9f0db776 authored by Marek Vavrusa's avatar Marek Vavrusa

modules/http: doc, auto-tls, cert renewal, ...

added documentation, many fixes in the H2 fallback
code and H2 stream handling, TLS is enabled by
default using ephemeral key and certificate that
is automatically renewed, but custom certificates
are also supported

this also allows other modules to place code
snippets on the webpage
parent 67afc023
.. _mod-http:
HTTP interface
HTTP/2 services
This module provides both DNS/HTTP(s) and web interface that cooperates with the internal
scheduler. It preloads all static assets, so nothing is read from disk after startup and
provides basic foundation for other services wishing to export services over HTTP endpoints.
The module supports HTTP/2, server push and all other shiny things thanks to lua-http.
This is a module that does the heavy lifting to provide an HTTP/2 enabled
server that supports TLS by default and provides endpoint for other modules
in order to enable them to export restful APIs and websocket streams.
One example is statistics module that can stream live metrics on the website,
or publish metrics on request for Prometheus scraper.
The server allows other modules to either use default endpoint that provides
built-in webpage, restful APIs and websocket streams, or create new endpoints.
Example configuration
By default, the web interface starts at port 8053 if HTTP or 4453 if running on TLS.
By default, the web interface starts HTTPS/2 on port 8053 using an ephemeral
certificate that is valid for 90 days and is automatically renewed. It is of
course self-signed, so you should use your own judgement before exposing it
to the outside world. Why not use something like `Let's Encrypt <>`_
for starters?
.. code-block:: lua
-- Load modules
-- Load HTTP module with defaults
modules = {
http = {
host = 'localhost',
port = 8080,
host = 'localhost',
port = 8053,
Now you can reach the web services and APIs, done!
.. code-block:: bash
$ curl -k https://localhost:8053
$ curl -k https://localhost:8053/stats
It is possible to disable HTTPS altogether by passing ``cert = false`` option.
While it's not recommended, it could be fine for localhost tests as, for example,
Safari doesn't allow WebSockets over HTTPS with a self-signed certificate.
Major drawback is that current browsers won't do HTTP/2 over insecure connection.
.. code-block:: lua
http = {
host = 'localhost',
port = 8053,
cert = false,
If you want to provide your own certificate and key, you're welcome to do so:
.. code-block:: lua
http = {
host = 'localhost',
port = 8053,
cert = 'mycert.crt',
key = 'mykey.key',
The format of both certificate and key is expected to be PEM, e.g. equivallent to
the outputs of following:
.. code-block:: bash
openssl ecparam -genkey -name prime256v1 -out mykey.key
openssl req -new -key mykey.key -out csr.pem
openssl req -x509 -days 90 -key mykey.key -in csr.pem -out mycert.crt
How to expose services over HTTP
The module provides a table ``endpoints`` of already existing endpoints, it is free for reading and
writing. It contains tables describing a triplet - ``{mime, on_serve, on_websocket}``.
In order to register a new service, simply add it to the table:
.. code-block:: lua
http.endpoints['/health'] = {'application/json',
function (h, stream)
-- API call, return a JSON table
return {state = 'up', uptime = 0}
function (h, ws)
-- Stream current status every second
local ok = true
while ok do
local push = tojson('up')
ok = ws:send(tojson({'up'}))
-- Finalize the WebSocket
Then you can query the API endpoint, or tail the WebSocket using curl.
.. code-block:: bash
$ curl -k http://localhost:8053/health
$ curl -k -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Host: localhost:8053/health" -H "Sec-Websocket-Key: nope" -H "Sec-Websocket-Version: 13" https://localhost:8053/health
HTTP/1.1 101 Switching Protocols
upgrade: websocket
sec-websocket-accept: eg18mwU7CDRGUF1Q+EJwPM335eM=
connection: upgrade
Since the stream handlers are effectively coroutines, you are free to keep state and yield using cqueues.
This is especially useful for WebSockets, as you can stream content in a simple loop instead of
chains of callbacks.
Last thing you can publish from modules are *"snippets"*. Snippets are plain pieces of HTML code that are rendered at the end of the built-in webpage. The snippets can be extended with JS code to talk to already
exported restful APIs and subscribe to WebSockets.
.. code-block:: lua
http.snippets['/health'] = {'Health service', '<p>UP!</p>'}
How to expose more interfaces
Services exposed in the previous part share the same external interface. This means that it's either accessible to the outside world or internally, but not one or another. This is not always desired, i.e. you might want to offer DNS/HTTPS to everyone, but allow application firewall configuration only on localhost. ``http`` module allows you to create additional interfaces with custom endpoints for this purpose.
.. code-block:: lua
http.interface('', 8080, {
['/conf'] = {'application/json', function (h, stream) print('configuration API') end},
['/private'] = {'text/html', static_page},
This way you can have different internal-facing and external-facing services at the same time.
This diff is collapsed.
// Colour palette
var colours = [
// Unit conversion
function tounit(d) {
d = parseInt(d);
......@@ -25,6 +35,27 @@ window.onload = function() {
data: statsHistory
var fills = { defaultFill: '#F5F5F5' };
for (var i in colours) {
fills['q' + i] = colours[i];
var map = new Datamap({
element: document.getElementById('map'),
fills: fills,
data: {},
height: 350,
geographyConfig: {
highlightOnHover: false,
borderColor: '#ccc',
borderWidth: 0.5,
popupTemplate: function(geo, data) {
return ['<div class="hoverinfo">',
'<strong>',, '</strong>',
'<br>Queries: <strong>', data ? data.queries : '0', '</strong>',
* Realtime updates over WebSockets
......@@ -52,7 +83,7 @@ window.onload = function() {
/* WebSocket endpoints */
var wsStats = 'ws://' + + '/stats';
var wsStats = (secure ? 'wss://' : 'ws://') + + '/stats';
var Socket = "MozWebSocket" in window ? MozWebSocket : WebSocket;
var ws = new Socket(wsStats);
ws.onmessage = function(evt) {
<!DOCTYPE html>
<meta charset="utf-8">
<title>{{ title }}</title>
body { font-family: 'Gill Sans', 'Gill Sans MT', Verdana, sans-serif; color: #555; }
h1, h2, h3 { line-height: 1.5em; color: #000; text-align: center; border-bottom: 1px solid #ccc; }
......@@ -13,24 +14,27 @@
#stats .layer-100ms , .l-100ms { fill: #258FDA; color: #258FDA; }
#stats .layer-1000ms , .l-1000ms { fill: #51A5E1; color: #51A5E1; }
#stats .layer-slow , .l-slow { fill: #E1AC51; color: #E1AC51; }
#feed { width: 100%; }
#feed .secure { color: #74c476; }
.stats-legend { text-align: center; }
.stats-legend li { display: inline; list-style-type: none; padding-right: 20px; }
.map-legend { font-size: 10px; }
<script type="text/javascript">
var host = "{{ host }}";
var secure = {{ secure }};
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="d3.js"></script>
<script type="text/javascript" src="epoch.js"></script>
<script type="text/javascript" src="topojson.js"></script>
<script type="text/javascript" src=""></script>
<script type="text/javascript" src="tinyweb.js"></script>
<script type="text/javascript" src="kresd.js"></script>
<link rel="icon" type="image/ico" href="favicon.ico">
<link rel="stylesheet" type="text/css" href="epoch.css">
<div id="page">
<h1>{{ title }}</h1>
<div class="epoch" id="stats"></div>
<ul class="stats-legend"></ul>
<h2>Frequent queries</h2>
<table id="feed"></table>
<h2>Where do the queries go?</h2>
<div id="map" style="position: relative;"></div>
{{ snippets }}
Markdown is supported
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment