7.6.8. HV-08 — HTTPS and WSS (TLS)

This tutorial covers serving over TLS. A server created with init_wss listens on both a plain HTTP port and an HTTPS port, using a certificate and private key on disk. The same route handlers serve both.

Prerequisites: HV-03 — HTTP Server Basics.

7.6.8.1. Starting a TLS Server

Where a plain server calls init(port), a TLS server calls init_wss(port, httpsPort). The server then accepts plain HTTP on port and TLS on httpsPort; the route API is unchanged:

class TutorialTlsServer : HvWebServer {
    def override onInit {
        GET("/secure") <| @(var req : HttpRequest?; var resp : HttpResponse?) : http_status {
            return resp |> TEXT_PLAIN("secure hello over TLS")
        }
    }
}

var server = new TutorialTlsServer()
server->init_wss(18091, 18443)   // HTTP on 18091, HTTPS on 18443
server->start()

7.6.8.2. The Certificate

init_wss takes an optional third argument — the directory holding server.crt and server.key. When omitted it defaults to modules/dasHV/cert, a self-signed pair that ships with dasHV:

server->init_wss(18091, 18443)                 // default cert dir
server->init_wss(18091, 18443, "/path/certs")  // your own crt/key

TLS requires that dasHV was built with OpenSSL (the build enables it by default). If the certificate files cannot be loaded, init_wss reports an error naming the expected server.crt / server.key paths.

7.6.8.3. Making an HTTPS Request

The client follows the https:// scheme and negotiates TLS automatically. The bundled certificate is self-signed, which the local client accepts:

GET("https://127.0.0.1:18443/secure") $(resp) {
    assert(resp.status_code == http_status.OK)
    // resp.body == "secure hello over TLS"
}

The same threaded server-lifecycle helper from HV-03 — HTTP Server Basics works unchanged — only init becomes init_wss and the client URL becomes https://.

Note

init_wss also enables secure WebSockets (wss://) on the TLS port for any WebSocket routes the server registers (see HV-06 — WebSockets).